0845 600 9231 Hopewiser on Facebook Hopewiser on Twitter

Hopewiser Web Services

Frequently Asked Questions

Common developer questions

Common administrative questions

Common errors caused by proxy or firewall configuration

AddressServer is an HTTP-based Web service that is delivered over TCP/IP. The operation, connectivity, and performance of AddressServer can be impacted by your proxy servers and firewall configuration.

What is the difference between AH21 and ListAPI Legacy Web Service facilities?

AH21 is a basic address lookup module based upon the input of a postcode (or part of a postcode) and an optional premise name or number. Without a postcode (even a part postcode) input, this module will not return any sensible data for you.

ListAPI offers a more generalised address search mechanism. This allows postcode and optional premise lookup, as above, but in addition also gives the capability of looking up on what we term partial addresses (possibly without an input postcode). Where the search criteria is vague or ambiguous, ListAPI has in-built access to the Hopewiser gazetteers providing a series of refinement step results in expandable nodes. This makes it possible (with user intervention) to match to a single delivery point despite the vague or ambiguous input given initially.

I get a 'timeout', 'unable to connect to remote server' or 'connection refused' message when trying to connect to the Hopewiser Web Service. Why is this?

The most common reason for these messages is that your outgoing firewall has not been configured to allow calls to the Hopewiser URL and/or port number concerned. Alternatively, it could be that the Web Service username and password being used is incorrectly stated in the calling request. Only requests from valid and currently enabled username and password combinations will be allowed. This is the only authentication needed to use the service.

How can I tailor what data is returned to me through the Legacy Web Service?

In terms of address data, the web service can either provide you with a formatted label, or separate address entities in 'fitting in' with your requirements. Details of available return fields and arrays can be found by reading the WSDL files linked to from here or documentation on the SOAP Service data fields.

How do I output an address label with fixed elements (e.g. fixed town, county and postcode) in the Legacy Web Service?

You can use the DISTRICT_LEVEL data item. This is a variable string array featuring all elements for the address matched up to and including postal district (e.g. premise number, house name, thoroughfare, etc). The single string items of TOWN, COUNTY and POSTCODE could then be utilised to populate the remainder of the address in their fixed position resulting in an address label with fixed town, county and postcode.

Why do I not get premise data returned to me on occasion?

When using the ListAPI Web Service facility, the address searches effectively take the form of a number of call 'levels'. A general search might give 3 'nodes' bearing information on matching districts or streets. These would, through the ListAPI methodology, need to be further expanded to obtain premise, sub-premise or organisation information. This is achieved by passing back the relevant node 'ID' via another request. The presence of this node ID denotes that there is more data to be had. A click will only be deducted from the Web Service user account holding on the initial lookup, not for each refinement step.

Why does a Web Service lookup result differ from what I would expect?

The Web Service results should not differ from the standard Atlas software we offer. A good first step (in identifying differences concerning Royal Mail Postal Address File) would be to try the main Hopewiser web site Free Address Search facility, and possibly the address search facility on the Royal Mail web site. If the results are the same, then this is what the Royal Mail PAF dataset currently holds. If the results differ, then there would appear to be an anomaly in the way that address is handled by the application issuing the initial request and the resulting response.

What documentation and samples are available in using the Hopewiser Web Service?

All documentation and code samples are published online here. You will find details of what can be achieved using the service, example code, WSDL files and examples of XML.

I am unable to use or am getting strange lookup results returned to me from Web Services. How can I diagnose the problem?

You can contact Hopewiser technical support (support@hopewiser.com) giving full details of the problem, any error codes and/or messages reported, as well as any output. The Hopewiser Services Team has the capability to turn on debugging on the account concerned (given the external IP address in use by the client) which may aid in identifying any connection or retrieval issues concerned.

You should also try to run the following two commands, which commonly prove useful in detecting client outbound connection issues:

  • telnet cloud.hopewiser.com 80
  • tracert cloud.hopewiser.com

What are the prerequisites for using the Hopewiser Web Service?

That you have a valid and enabled Web Service account (organised through your Hopewiser account manager), that the assigned username and password combination are utilised in making requests to the service, and that the outbound SOAP requests are allowed through client external firewall. The relevant details are here.

What reference datasets are available for use through the Hopewiser Web Services?

A list of datasets we provide is listed here.

The name to be used to access a particular dataset will depend on which options you have purchased. If you are unsure which name to use, please contact support.

How can I find out administration information about my Web Service account (e.g. how much credit I have left, when the account is set to expire, etc)?

We will shortly be introducing management pages which will enable you to see and update your account information. In the meantime please contact your account manager who will be able to help.

Why does my bundle have the status Ready?

A bundle will be given the status Ready if a Non-Test Active bundle exists on the same Plan and Cost Centre at the time of purchase (otherwiser it will become an Active bundle immediately). The status Ready indicates that the purchase was successful and that the bundle is available for use.

When is a 'click' deducted from my Web Services account?

A single click is deducted from a Web Services account whenever a request is successfully made to the service which looks up against a dataset. Functions which do not reference a dataset (e.g. login, version, logout) are not charged. When using tree searches only the initial lookup is charged, requests to descend to subsequent levels are not.

When are updates applied to the Hopewiser Web Services?

Essential maintenance (in keeping with the Web Services SLA) is undertaken on the last Wednesday of every month between the hours of 09:00 and 11:00 (UK time). Ordinarily, the updates made are limited to the various reference datasets provided through the service, although periodic updates to underlying software may also be applied then too. You will be notified in advance of any significant software updates via email to the client Web Services account contact.

How can I ensure I have no Hopewiser Web Services downtime?

Notifications are sent when you have used 80% and again at 90% of your credit and 14 and 7 days before your account expires (note: only a 1-week notice is sent to users who have not asked us to migrate their account to AddressServer).

The email notification is sent to the contact provided when the account was set up. It is important, therefore, that we are informed of any changes to contact information at the earliest convenience.

In each of the above cases, to avoid your account being disabled and the downtime this will result in, please contact your Hopewiser account manager before all account credit is used, or the cited expiry date is surpassed.

To avoid temporary downtime when a server becomes unavailable you should set up a suitable failover option.

What is the Hopewiser Web Services 'timeout'?

There are actually two different timeouts: a lookup timeout and a session timeout. The lookup timeout is 5 seconds. This is to prevent overly vague address lookups from adversely affecting lookup performance or client application usability. The session timeout is 30 minutes. An assigned session ID is retained for this period after it is last used. Any number of calls to the Web Service using this session ID within this timeframe should yield results.

The underlying connection was closed: The remote name could not be resolved.

This error typically occurs if the network environment routes traffic through an HTTP proxy server, and the client application cannot read the proxy settings automatically from the Windows registry.

The problem is more likely to occur if the Web service client is an ASP.NET web application, because Web applications do not typically run on an interactive user account. Therefore, Web applications do not always have access to the browser proxy settings in the registry.

To resolve this error, use one of the three following options:

  1. Configure the proxy server in Machine.config by modifying the defaultProxy element as follows:

    <defaultProxy>
        <proxy usesystemdefault = "false"
                  proxyaddress="http://proxyserver:port"
                  bypassonlocal="true"/>
    </defaultProxy>
    

  2. Configure the proxy server in Web.config by adding the defaultProxy element as a child of the System.net element.
  3. Configure the proxy server as code as follows:
    • Visual Basic .NET

      Dim myProxy As New WebProxy("http://proxyserver:port", True)
      myProxy.Credentials = New NetworkCredential("username", "password", "domain")
      Dim myFindService As New FindServiceSoap()
      myFindService.Proxy = myProxy
      

    • C#

      WebProxy myProxy = new WebProxy("http://proxyserver:port",true);
      myProxy.Credentials = new NetworkCredential("username", "password", "domain");
      FindServiceSoap myFindService = new FindServiceSoap();
      myFindService.Proxy = myProxy;
      

Note, you must set the proxy for each SOAP service that you call. Also, you must use the IMPORTS statement for Visual Basic .NET or the Using directive for C# to reference the "System.Net" namespace to have access to the WebProxy class.

The request failed with HTTP status 502: Proxy Error

This error may occur if the SOAP web service is behind a proxy server or a firewall that enforces limits on SOAP packet size, or that has a timeout value that is less than the time it takes for a large request to return.

For example, a call to a mapping service to render a map with a large number of pushpins causes a large SOAP packet to be returned, and causes a request that takes longer to process than the timeout value allows. This may cause the request to fail, depending on the proxy and firewall configuration for the network.

To resolve this error bypass the proxy or do the following:

  • Configure the proxy server to accept large SOAP packets.
  • Increase the timeout value for requests.
  • Limit the data that you request.

Each solution may be different and the correct solution depends on the network environment that you use to call the Web service.

Work with your network administrator to determine the specific settings that are required for the SOAP packets to be successfully sent to and received from the SOAP web service.

The request failed with the error message: -- Server Error in '/Find-20' Application. Request format is unrecognized.

This error may occur if a proxy or firewall is set to remove unknown headers. The complete error is:

"The request failed with the error message: -- Server Error in '/Find-20' Application.
-------------------------------------------------------------------------------
Request format is unrecognized.
Description: An unhandled exception occurred during the execution of the current
web request. Please review the stack trace for more information about the error
and where it originated in the code.
Exception Details: System.InvalidOperationException: Request format is unrecognized."

Work with your network administrator to correctly configure your firewall to accept the SOAP headers. In some cases, you can just select the Remove Unknown Headers box in the firewall configuration.

The request failed with HTTP status 407: Proxy authentication required.

This error occurs if the proxy server requires authentication from a domain user account and if the SOAP web service client is an ASP.NET application. The complete error is:

The request failed with HTTP status 407: Proxy authentication required.
Description: An unhandled exception occurred during the execution of the current
web request. Please review the stack trace for more information about the error
and where it originated in the code.
Exception Details: System.Net.WebException: The request failed with HTTP status
407: Proxy authentication required."

ASP.NET applications typically run on the security context of a local user account that does not have permissions on the network and proxy server.

Configure the proxy server in code as follows:

  • Visual Basic .NET

    Dim myProxy As New WebProxy("http://proxyserver:port", True)
    myProxy.Credentials = New NetworkCredential("username", "password", "domain")
    Dim myFindService As New FindServiceSoap()
    myFindService.Proxy = myProxy
    

  • C#

    WebProxy myProxy = new WebProxy("http://proxyserver:port",true);
    myProxy.Credentials = new NetworkCredential("username", "password", "domain");
    FindServiceSoap myFindService = new FindServiceSoap();
    myFindService.Proxy = myProxy;
    

Note, you must set the proxy for each SOAP service that you call. Also, you must use the IMPORTS statement for Visual Basic .NET or the Using directive for C# to reference the "System.Net" namespace to have access to the WebProxy class.




Next page: For Developers