Skip to main content

Loqate Tomcat REST Interface

Lauren Wheeler
  • Updated

This tutorial and sample code are provided as an example only. Please use this as a guideline for your implementation and do not consider this to be production-ready code.

This is a new RESTful web services interface for users to run locally with Loqate Local API.

This interface allows an organization to provide address verification as a web service through their corporate intranet and accessible to their employees.

This is a key interface used, for example, by Loqate customers needing to provide address verification and geocoding while complying with legal restrictions that impede customer data from leaving their premises. This is simply achieved by installing the Loqate Local API and the Loqate Tomcat REST interface.

 

Installation

The Tomcat Manager interface can be used to deploy the downloaded WAR file. The only configuration required is to ensure that the native Loqate libraries are accessible to Tomcat. This can be achieved by adding the following lines to catalina.sh (fromhttp://stackoverflow.com/questions/14018817/how-to-add-native-library-in-tomcat):

# Set java.library.path
JAVA_OPTS=”$JAVA_OPTS -Djava.library.path=/opt/loqate”

 

Tomcat REST Functional Reference

API Usage

The following code walks through API usage.

1. Create Loqate Server

GET: /Loqate/server/?… (input object serialized by jquery.param())
POST: /Loqate/server/

Input

{
	"path" : "[Path To Data]",
	"poolSize" : "[Number of lqtServer instances in pool]", //(optional)
	"lqtServerOptions": { //(optional)
	        option_name_1: option_value_1,
	        option_name_2: option_value_2,
		...
	}
}

Output

{
	"status": "OK",
	"ServerId": (String) new_server_id //(optional)
}

Failed Output

{
	"status": (String) lqtServer_status,
	"ErrorMessage": (String) lqtserver_lasterror
}

Sample Input (with JSON Object)

{
	"path" : "/opt/loqate/data/"
}

Sample Input (with XML Object)

<lqt>
    <path>
	/opt/loqate/data/
    </path>
</lqt>

 

Run a Process

GET: /Loqate/server/{server id}/process?…. (input object serialized by jquery.param())
POST: /Loqate/server/{server id}/process
GET: /Loqate/server/process?…. (input object serialized by jquery.param())
POST: /Loqate/server/process

Note: For each field’s data, default values are shown below, and if the data is the default value, it won’t be outputted.

{
"Confidence" : "0",
"MatchScore" : "0.0",
"Status" : "10",
"Value" : "",
"Info" : ""
}

For example:

{
"Confidence" : "0",
"MatchScore" : "0.0",
"Status" : "3",
"Info" : "",
"Value" : "1111 Bayhill Dr Ste 420"
}

will be returned as:

{
"Status" : "3",
"Value" : "1111 Bayhill Dr Ste 420"
}

 

Input

{
	"lqtServerOptions": {
		serverOptionName1: serverOptionValue1,
		serverOptionName1: serverOptionValue2
	},
	"lqtInputRecord": {
		fieldName1: fieldValue1,
		fieldName3: fieldValue3,
		...
	},
	"lqtProcessList": [
		{
			"type": processType,
			"lqtProcessOptions": {
				processOptionName1: processOptionValue1,
				processOptionName2: processOptionValue12
			},
		},
		...
	],
}

Output

{
	"status": "OK",
	"results": list of results
}

Failed Output

{
	"status": (String) lqtServer_status,
	"ErrorMessage": (String) lqtserver_lasterror
}

Sample input: (with JSON Object)

{
	"lqtInputRecord": {
		"Country": "USA",
		"Address1": "1111 bayhill dr",
		"Locality": "san bruno",
		"AdministrativeArea": "ca"
	},
	"lqtProcessList": [
		{
			"type": "Verify"
		},
		{
			"type": "Geocode"
		}
	]
}

Sample Input (with XML Object)

<lqt>
  <lqtInputRecord>
    <Country>USA</Country>
    <Address1>1111 bayhill dr san bruno ca</Address1>
  </lqtInputRecord>
  <lqtProcessList>
    <type>Search</type>
  </lqtProcessList>
  <lqtProcessList>
    <type>Geocode</type>
  </lqtProcessList>
</lqt>

Sample output:

{ "results" : [ { "AVC" : { "Value" : "V54-I55-P3-100"
		  },
		"Address" : { "Confidence" : "1190",
			"MatchScore" : "66.666664",
			"Status" : "3",
			"Value" : "1111 Bayhill Dr Ste 420
San Bruno CA 94066-3067"
		  },
		"Address1" : { "Status" : "3",
			"Value" : "1111 Bayhill Dr Ste 420"
		  },
		"Address2" : { "Status" : "3",
			"Value" : "San Bruno CA 94066-3067"
		  },
		"AdministrativeArea" : { "Confidence" : "215",
			"MatchScore" : "100.0",
			"Status" : "1",
			"Value" : "CA"
		  },
		.....many other address fields....,
		"_L" : { "Status" : "5",
			"Value" : "Search|Country|Parse|Lexicon:TABLE=lx_US1|RefLex:TABLE=rd_US_vfy;POSTCODECHECK=Yes;POSTCODEFIELD=PostalCode|Signal:MATCHTYPES=Address|Context:TABLE=CT_US_Fast;BREAKONMATCH=Yes|Context:COMPLETEMATCH=Yes;TABLE=CT_USAD_Fast;BREAKONMATCH=Yes|Signal:MATCHTYPES=Address"
		  }
	  } ],
  "status" : "OK"
}

 

Shut Down Loqate Server

GET/POST: /Loqate/server/{server id}/destroy
OR /Loqate/server/{server id}/shutdown
GET/POST: /Loqate/server/destroy
OR /Loqate/server/shutdown

Input

Not needed.

Output

{
	"status": "OK"
}

Failed Output

{
	"status": "error",
	"ErrorMessage": (String) Error_message
}



Get Server Option

GET: /Loqate/server/{server id}/option/{option name}
GET: /Loqate/server/option/{option name}

Input

Not needed.

Output

{
	"status": "OK",
	"OptionValue": (String) server_option_value
}

Failed Output

{
	"status": (String) lqtServer_status,
	"ErrorMessage": (String) lqtserver_lasterror
}

Sample:

/Loqate/server/12345/option/MaxResults
{"status":"OK","OptionValue":"1"}

 

Set Server Option

POST: /Loqate/server/{server id}/option/
POST: /Loqate/server/option/

Input

{
	option_name_1: option_value_1,
	option_name_2: option_value_2,
	...
}

Output

{
	"status": "OK",
}

Failed Output

{
	"status": (String) lqtServer_status,
	"ErrorMessage": (String) lqtserver_lasterror
}



Get Last Server Error

GET: /Loqate/server/{server id}/lasterror
GET: /Loqate/server/lasterror

Input

{
Not needed.
}

Output

{
	"status": "OK",
	"LastError": (String) last_error_message
}

Failed Output

{
	"status": (String) lqtServer_status,
	"ErrorMessage": (String) lqtserver_lasterror
}

 

 

Get Server Status

GET: /Loqate/server/{server id}/status

Output

{
	"status": "OK",
        "ServerStatus": (String) server_status_message
}

Failed Output

{
	"status": (String) lqtServer_status,
	"ErrorMessage": (String) lqtserver_lasterror
}

GET: /Loqate/server/status

Output

{
	"status": "OK",
	"size": 10,
	"lqtServerOptions": { "MaxResults" : "10" }
}

Failed Output

{
	"status": (String) lqtServer_status,
	"ErrorMessage": (String) lqtserver_lasterror
}

 

 

Get Loqate Server Version

GET: /Loqate/server/{server id}/version
GET: /Loqate/server/version

Output

{
	"status": "OK",
	"Version": "2.5.0.4716"
}

Failed Output

{
	"status": (String) lqtServer_status,
	"ErrorMessage": (String) lqtserver_lasterror
}

Sample Output

{"status":"OK","Version":"2.3.0.4284"}

 

 

Read Registry

GET: /Loqate/server/{server id}/readregistry?tablename=&key=
GET: /Loqate/server/readregistry?tablename=&key=

Output

{
	"status": "OK",
	"content": (String) result_content
}

Failed Output

{
	"status": (String) lqtServer_status,
	"ErrorMessage": (String) lqtserver_lasterror
}

 

 

Log to Server Log

POST: /Loqate/server/{server id}/log

Input

{
	"msg": message
}

Output

{
	"status": "OK",
}

Failed Output

{
	"status": (String) lqtServer_status,
	"ErrorMessage": (String) lqtserver_lasterror
}

 

 

Error Status Codes

HTTP Error 400 Bad request

[Error 400 with valid response] Server id not exist (while calling server).

{
	'status': 'error',
	'ErrorMessage': 'loqateWebService.InvalidServerIdException: Server ID not exist.'
}

 

[Default error 400] Other bad request (i.e. invalid request xml format, un-readable input, server id correct, but function not valid, etc).

HTTP Error 500 Internal server error

[Default error 500] Server internal function error.

 

 

 

 

Related articles