{ "openapi": "3.0.0", "info": { "title": "LocationServices_LocationManagement_CreateList", "description": "", "version": "1.1" }, "servers": [ { "url": "https://api.addressy.com" } ], "paths": { "/LocationServices/LocationManagement/CreateList/v1.10/json6.ws": { "post": { "tags": [ "LocationServices_LocationManagement_CreateList" ], "summary": "LocationServices_LocationManagement_CreateList", "description": "", "operationId": "LocationServices_LocationManagement_CreateList", "requestBody": { "x-name": "body", "content": { "application/json": { "schema": { "title": "CreateListRequest", "allOf": [ { "$ref": "#/components/schemas/RequestItemKeyRequired" }, { "type": "object", "additionalProperties": false, "properties": { "ListName": { "type": "string", "description": "The name of the list being created." }, "ListDescription": { "type": "string", "description": "A description of the list being created." }, "Locations": { "type": "array", "description": "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.**", "items": { "$ref": "#/components/schemas/PointData" } }, "CreatedOn": { "type": "string", "format": "date-time", "nullable": true }, "LastModifiedOn": { "type": "string", "format": "date-time", "nullable": true }, "Geocoding": { "type": "boolean", "description": "A Boolean that determines whether the addresses passed in the locations object will be geocoded. Set to FALSE by default." } } } ] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "title": "ExternalEndpointResponse", "type": "object", "additionalProperties": false, "properties": { "ListId": { "type": "string", "description": "An automatically generated GuID used to uniquely identify a list." }, "ListName": { "type": "string", "description": "The name of the list passed in the request." }, "ListDescription": { "type": "string", "description": "The description of the list passed in the request." }, "LatestRelatedListId": { "type": "string" }, "IsErrorList": { "type": "boolean" }, "Locations": { "type": "array", "description": "An array of strings that is populated with information about a location. Also contains a uniquely generated GuID per point.", "items": { "$ref": "#/components/schemas/ExternalResponsePointData" } }, "CreatedOn": { "type": "string", "description": "The date and time of when the list was initially created.", "format": "date-time", "nullable": true }, "LastModifiedOn": { "type": "string", "description": "The date and time of when the list was last modified.", "format": "date-time", "nullable": true } } } } } }, "500": { "description": "InternalServerError", "content": { "application/json": { "schema": { "title": "ErrorResponseSelfContained", "type": "object", "additionalProperties": false, "properties": { "Number": { "type": "integer", "format": "int32" }, "Description": { "type": "string" }, "Cause": { "type": "string" }, "Resolution": { "type": "string" } } }, "examples": { "Unknown error": { "summary": "Unknown error", "value": { "Number": -1, "Description": "Unknown error", "Cause": "The cause of the error is unknown but details have been passed to our support staff who will investigate.", "Resolution": "These problems are typically short lived and are often resolved by trying again in a few minutes." } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "title": "ErrorResponseSelfContained", "type": "object", "additionalProperties": false, "properties": { "Number": { "type": "integer", "format": "int32" }, "Description": { "type": "string" }, "Cause": { "type": "string" }, "Resolution": { "type": "string" } } }, "examples": { "Unknown key": { "summary": "Unknown key", "value": { "Number": 2, "Description": "Unknown key", "Cause": "The key you are using to access the service was not found.", "Resolution": "Please check that the key is correct. It should be in the form AA11-AA11-AA11-AA11." } }, "Agreement Not Signed": { "summary": "Agreement Not Signed", "value": { "Number": 23, "Description": "Agreement Not Signed", "Cause": "There are agreements associated with service which are not signed.", "Resolution": "Please go to your account and check your agreements." } }, "Not enough credit for request": { "summary": "Not enough credit for request", "value": { "Number": 24, "Description": "Not enough credit for request", "Cause": "There is not enough credit on the account to process the request.", "Resolution": "Please topup your account with credit." } }, "Unexpected error, please contact the help desk for more information": { "summary": "Unexpected error, please contact the help desk for more information", "value": { "Number": 25, "Description": "Unexpected error, please contact the help desk for more information", "Cause": "", "Resolution": "" } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "title": "ErrorResponseSelfContained", "type": "object", "additionalProperties": false, "properties": { "Number": { "type": "integer", "format": "int32" }, "Description": { "type": "string" }, "Cause": { "type": "string" }, "Resolution": { "type": "string" } } }, "examples": { "Account out of credit": { "summary": "Account out of credit", "value": { "Number": 3, "Description": "Account out of credit", "Cause": "Your account is either out of credit or has insufficient credit to service this request.", "Resolution": "Please check your account balance and top it up if necessary." } }, "Web service not available on your plan": { "summary": "Web service not available on your plan", "value": { "Number": 7, "Description": "Web service not available on your plan", "Cause": "The requested web service is not currently available on your payment plan.", "Resolution": "Some services are only available in specific regions due to licensing restrictions. Please contact us for more information." } }, "Key daily limit exceeded": { "summary": "Key daily limit exceeded", "value": { "Number": 8, "Description": "Key daily limit exceeded", "Cause": "The daily limit on the key has been exceeded.", "Resolution": "Alter the daily limit on the key. Check the usage details first to see if usage is normal." } }, "Your account has been suspended": { "summary": "Your account has been suspended", "value": { "Number": 9, "Description": "Your account has been suspended", "Cause": "Your account has been suspended. This can be for a number of reasons including non-payment of an invoice.", "Resolution": "Please contact us in order to resolve this issue." } }, "Surge protector triggered": { "summary": "Surge protector triggered", "value": { "Number": 10, "Description": "Surge protector triggered", "Cause": "An unusually large number of requests have been processed for your account so the surge protector has been enabled.", "Resolution": "You can disable the surge protector at any time but this is only recommended if you are running through a batch of requests." } }, "No valid license available": { "summary": "No valid license available", "value": { "Number": 11, "Description": "No valid license available", "Cause": "The request requires a valid license but none were found.", "Resolution": "Please check your purchase history. You may be using a license that is no longer valid or of an incorrect type." } }, "Management key required": { "summary": "Management key required", "value": { "Number": 12, "Description": "Management key required", "Cause": "To use this web service you require a management key. Management can be enabled on any key, but we advise you to use management keys with care.", "Resolution": "Sign in to the website and create a new management key or change an existing key." } }, "Demo limit exceeded": { "summary": "Demo limit exceeded", "value": { "Number": 13, "Description": "Demo limit exceeded", "Cause": "The daily demonstration limit for this service or account has been exceeded.", "Resolution": "The limit will be reset at midnight tonight. If you would like the limit increased, please contact us." } }, "Free service limit exceeded": { "summary": "Free service limit exceeded", "value": { "Number": 14, "Description": "Free service limit exceeded", "Cause": "You have used too many free web services.", "Resolution": "Our web services are designed to operate in stages. The first is usually a Find service followed by a Retrieve. If you use too many Finds without the corresponding number of Retrieves you will receive this error. For more information, please contact us." } }, "Wrong type of key": { "summary": "Wrong type of key", "value": { "Number": 15, "Description": "Wrong type of key", "Cause": "The type of key you're using isn't supported by this web service.", "Resolution": "This usually happens if you're using a user or server license with a web service that only supports transactional keys. Please use another key and try again." } }, "Key expired": { "summary": "Key expired", "value": { "Number": 16, "Description": "Key expired", "Cause": "The key you are trying to use has expired.", "Resolution": "Please check that you are using the right key. A new one may have been issued if you recently renewed your key. Contact us if you have any questions." } }, "Individual User exceeded Lookup Limit": { "summary": "Individual User exceeded Lookup Limit", "value": { "Number": 17, "Description": "Individual User exceeded Lookup Limit", "Cause": "An Individual User has exceeded their daily lookup limit on the key and that user will be prevented from using your service until tomorrow (GMT)", "Resolution": "Check the usage details. If required, increase the Lookup Limit per Individual User or add the specific Individual User's IP to the Limiter Exclusions" } }, "Additional account verification required to use this web service on a Trial account.": { "summary": "Additional account verification required to use this web service on a Trial account.", "value": { "Number": 26, "Description": "Additional account verification required to use this web service on a Trial account.", "Cause": "The requested web service cannot be used on a Trial account without additional account verification.", "Resolution": "To use this web service, please add a payment card to your account or speak to your account manager." } } } } } }, "400": { "description": "BadRequest", "content": { "application/json": { "schema": { "title": "ErrorResponseSelfContained", "type": "object", "additionalProperties": false, "properties": { "Number": { "type": "integer", "format": "int32" }, "Description": { "type": "string" }, "Cause": { "type": "string" }, "Resolution": { "type": "string" } } }, "examples": { "Request not allowed from this IP": { "summary": "Request not allowed from this IP", "value": { "Number": 4, "Description": "Request not allowed from this IP", "Cause": "The request was disallowed from the IP address.", "Resolution": "Check the security settings on the key first. If they look fine, please contact support as it may be from an IP address on our blacklist." } }, "Request not allowed from this URL": { "summary": "Request not allowed from this URL", "value": { "Number": 5, "Description": "Request not allowed from this URL", "Cause": "The request was disallowed from the URL.", "Resolution": "Check the security settings on the key first. If they look fine, please contact support as it may be from a URL on our blacklist." } }, "Web service not available on this key": { "summary": "Web service not available on this key", "value": { "Number": 6, "Description": "Web service not available on this key", "Cause": "The requested web service is disallowed on this key.", "Resolution": "Check the security settings on the key first. You can limit a key to certain web services." } }, "Missing or invalid parameters": { "summary": "Missing or invalid parameters", "value": { "Number": 18, "Description": "Missing or invalid parameters", "Cause": "A required parameter was not supplied of the value of a parameter cannnot be converted into the right type.", "Resolution": "Check the parameters passed and their values against the specification for this service." } }, "Invalid JSON object": { "summary": "Invalid JSON object", "value": { "Number": 19, "Description": "Invalid JSON object", "Cause": "The JSON object sent in your request is invalid.", "Resolution": "Please ensure your JSON object is syntactically correct and try again." } }, "Endpoint not available": { "summary": "Endpoint not available", "value": { "Number": 20, "Description": "Endpoint not available", "Cause": "The web service you are calling is not available on this endpoint", "Resolution": "Refer to our documentation pages to ensure you are calling a valid endpoint for the web service you are requesting." } }, "Sandbox Mode is not available on this endpoint": { "summary": "Sandbox Mode is not available on this endpoint", "value": { "Number": 21, "Description": "Sandbox Mode is not available on this endpoint", "Cause": "The License key used has Sandbox Mode enabled, but the testing functionality is not available on this endpoint.", "Resolution": "Disable the Sandbox Mode on the License key." } }, "HTTPS requests only": { "summary": "HTTPS requests only", "value": { "Number": 22, "Description": "HTTPS requests only", "Cause": "As of 3rd September 2018 all new accounts must use HTTPS.", "Resolution": "Ensure you consume all of our APIs over HTTPS and not HTTP." } }, "Unexpected Error": { "summary": "Unexpected Error", "value": { "Number": 1000, "Description": "Unexpected Error", "Cause": "The cause of the error is unknown but details have been passed to our support staff who will investigate.", "Resolution": "These problems are typically short lived and are often resolved by trying again in a few minutes.." } }, "Listname Error.": { "summary": "Listname Error.", "value": { "Number": 1002, "Description": "Listname Error.", "Cause": "Listname Not Supplied.", "Resolution": "Please supply Listname." } }, "Point name Error.": { "summary": "Point name Error.", "value": { "Number": 1005, "Description": "Point name Error.", "Cause": "Point Supplied with no name.", "Resolution": "Check input data." } }, "Location Management operations required a Management Key": { "summary": "Location Management operations required a Management Key", "value": { "Number": 1010, "Description": "Location Management operations required a Management Key", "Cause": "Location Management operations required a Management Key", "Resolution": "Ensure you are using a Management key created by adding a Store Finder service to your Loqate account" } } } } } } } } } }, "components": { "securitySchemes": { "ApiKeyQuery": { "type": "apiKey", "name": "Key", "in": "query" } }, "schemas": { "PointData": { "type": "object", "additionalProperties": false, "properties": { "Name": { "type": "string", "description": "The name of the location." }, "Description": { "type": "string", "description": "The description of the location for display purposes." }, "Address": { "type": "string", "description": "The address of the location for display purposes. **If Geocoding is set to TRUE then this parameter is mandatory.**" }, "Country": { "type": "string", "description": "The ISO2 or ISO3 country code. **If Geocoding is set to TRUE then this parameter is mandatory.**" }, "Latitude": { "type": "string", "description": "The WGS 84 latitude in decimal degrees format. This is mandatory unless Geocoding is set to TRUE." }, "Longitude": { "type": "string", "description": "The WGS 84 longitude in decimal degrees format. This is mandatory unless Geocoding is set to TRUE." }, "MetaInfo": { "type": "object", "description": "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'", "additionalProperties": { "type": "string" } }, "UnstructuredMetaInfo": { "type": "object", "additionalProperties": {} }, "OpeningHours": { "description": "An object containing opening hours for the specified location. Each day supports optional Open, Close, and Information fields (String). If unused, set the object to null (e.g. \"OpeningHours\": null) - this reduces payload size and increases the maximum number of storable locations.", "$ref": "#/components/schemas/OpeningHours" } } }, "OpeningHours": { "type": "object", "additionalProperties": false, "properties": { "Monday": { "$ref": "#/components/schemas/Day" }, "Tuesday": { "$ref": "#/components/schemas/Day" }, "Wednesday": { "$ref": "#/components/schemas/Day" }, "Thursday": { "$ref": "#/components/schemas/Day" }, "Friday": { "$ref": "#/components/schemas/Day" }, "Saturday": { "$ref": "#/components/schemas/Day" }, "Sunday": { "$ref": "#/components/schemas/Day" } } }, "Day": { "type": "object", "additionalProperties": false, "properties": { "Open": { "type": "string" }, "Close": { "type": "string" }, "Information": { "type": "string" } } }, "RequestItemKeyRequired": { "allOf": [ { "$ref": "#/components/schemas/RequestItem" }, { "type": "object", "additionalProperties": false, "required": [ "Key" ], "properties": { "Key": { "type": "string", "description": "The key you want to use to authenticate with the service (you can request we create one for you or create one in your [account section](https://account.loqate.com/account#/)).", "default": "AA11-AA11-AA11-AA11" } } } ] }, "RequestItem": { "type": "object", "additionalProperties": false, "properties": { "Key": { "type": "string" } } }, "ExternalResponsePointData": { "type": "object", "additionalProperties": false, "properties": { "Id": { "type": "string", "description": "The id of the location." }, "Name": { "type": "string", "description": "The name of the location." }, "Description": { "type": "string", "description": "The description of the location for display purposes." }, "Address": { "type": "string", "description": "The address of the location for display purposes." }, "Country": { "type": "string", "description": "The ISO2 or ISO3 country code." }, "Latitude": { "type": "string", "description": "The WGS 84 latitude in decimal degrees format." }, "Longitude": { "type": "string", "description": "The WGS 84 longitude in decimal degrees format." }, "MetaInfo": { "type": "object", "description": "A key value pair that can be used to store any other relevant information.", "additionalProperties": { "type": "string" } }, "UnstructuredMetaInfo": { "type": "object", "additionalProperties": {} }, "OpeningHours": { "description": "An object containing opening hours information for the specified location. Each day can have optional Open, Close and Information fields of type String.", "$ref": "#/components/schemas/ExternalResponseOpeningHours" } } }, "ExternalResponseOpeningHours": { "type": "object", "additionalProperties": false, "properties": { "Monday": { "$ref": "#/components/schemas/ExternalResponseDay" }, "Tuesday": { "$ref": "#/components/schemas/ExternalResponseDay" }, "Wednesday": { "$ref": "#/components/schemas/ExternalResponseDay" }, "Thursday": { "$ref": "#/components/schemas/ExternalResponseDay" }, "Friday": { "$ref": "#/components/schemas/ExternalResponseDay" }, "Saturday": { "$ref": "#/components/schemas/ExternalResponseDay" }, "Sunday": { "$ref": "#/components/schemas/ExternalResponseDay" } } }, "ExternalResponseDay": { "type": "object", "additionalProperties": false, "properties": { "Open": { "type": "string" }, "Close": { "type": "string" }, "Information": { "type": "string" } } } } }, "security": [ { "ApiKeyQuery": [] } ] }