Finder Web Service

Overview

Our web services allow software developers to connect their applications to Ohio tax rate information over the internet. In addition to using TheFinder web site, businesses can use these services to add real-time Ohio tax rate lookups to their own software. Developers who use these services should have experience building web-based applications and services.

Registration

To use our web services, email us at thefinderhelp@tax.ohio.gov and use "Finder Web Service Registration" as the subject line.

Using the Service

The Finder web services are available at OHFinder Service site.

This page includes:

A list of available web service methods
Instructions for how to use each method
Detailed WSDL for developers familiar with web service standards
A test application you can use to try the service

The test application runs through a web browser, but it still uses the web service to look up Ohio tax rates.

WS-Security

We implement the WS-Security standard for verifying users. Since we use Secure Sockets Layer (SSL) for our web services, you can rest assured that your credentials are secure.

With WS-Security, the username/password is sent in the SOAP (Simple Object Access Protocol) header of a web service request.

The following is a sample SOAP header. The body of the request will appear different depending on whether you're looking up an address or zip code.

<?xml version="1.0" encoding="ISO-8859-1"?>
                            <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
                            xmlns:xsd="http://www.w3.org/2001/XMLSchema"
                            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                            xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
                            xmlns:si="http://soapinterop.org/xsd"
                            xmlns:ns5925="https://thefinder.tax.ohio.gov/OHFinderService">
                            <SOAP-ENV:Header>
                                <wsse:Security>
                                    <wsse:UsernameToken>
                                        <wsse:Username>USERNAME</wsse:Username>
                                        <wsse:Password Type="wsse:PasswordText">PASSWORD</wsse:Password>
                                    </wsse:UsernameToken>
                                </wsse:Security>
                            </SOAP-ENV:Header>
                            <SOAP-ENV:Body>
                                ...
                            </SOAP-ENV:Body>
                            </SOAP-ENV:Envelope>

WS-Security Resources

The following are some additional resources on WS-Security:

Sample code for .Net

To get a head start using our web services, we have sample .Net C# code for developers to reference. This code sample and instructions are provided for Visual Studio.Net users.

If you use another development tool, you will need to alter these instructions.

Make sure you install the latest version of Microsoft's Web Services Extensions (WSE)
Create a new project in Visual Studio.Net
Using Visual Studio, add a web reference to https://thefinder.tax.ohio.gov/OHFinderService/OHFinderService.asmx. With WSE installed, it will also generate WSE versions of web service stubs.
With WSE installed, it will also generate WSE versions of web service stubs.

Try out the following sample code, substituting valid login/address data for the values in [brackets].

// Create new instance of web service reference using WSE
                            OHFinderServiceWse finderService = new OHFinderServiceWse();

                            // Create authentication token
                            UsernameToken tkn = new UsernameToken("[username]", "[password]", PasswordOption.SendPlainText);

                            // Add authentication token to web service request
                            finderService.RequestSoapContext.Security.Tokens.Add(tkn);

                            // Create new date for method calls
                            DateTime todayDate = new DateTime();

                            // Tax rate lookup by address...
                            Finder.AddressReturn addressReturn = finderService.GetOHSalesTaxByAddress(
                            "[address]", "[city]", "[state abbr]", "[postal code]", "US",
                            [tax amount], todayDate, [true/false]);

                            // addressReturn.addressResponse contains the standardized address
                            // addressReturn.taxResponse contains an array of tax return values

                            // Tax rate lookup by zip code...
                            Finder.ZipCodeReturn zipReturn = finderService.GetOHSalesTaxByZipCode(
                            "[postal code]", [tax amount], todayDate, [true/false]);

                            // zipReturn.zipResponse contains the original zip code queried
                            // zipReturn.taxResponse contains an array of tax return values

Sample Code for Java (using Apache Axis)

Apache Axis is an open-source SOAP tool. It is mostly used to create web services, but it can also be used by applications to connect with and use those services.

We provide sample code using this tool as an example of how a Java client can call a web service. It is important in Java to mention different toolsets can provide different approaches to calling web services.

In Java, different tools can be used to connect to web services in different ways. If you have questions, contact the vendor to find out if they support calling web services.

Instructions are for Java developers

Download and install JDK 1.4+ or later if you do not already have it.
Add a PATH entry to point to the Java "bin" directory. (optional)
Download Axis Apache and install files to directory.
Download Axis-wsse Apache and install files.
Add CLASSPATH entry to point to the individual jar files within the Axis Apache "lib" directory and to the Axis-wsse jar file.
Call the WSDL2Java utility in wsdl4j.jar to generate stub classes off of the WSDL.
Modify OHFinderServiceSoapStub.java to include authentication information (see below).
Create a test client to call the web services (see the TestClient.java instructions).

OHFinderServiceSoapStub.java

...
                            // In each individual method call, for getOHSalesTaxByAddress
                            // and getOHSalesTaxByZipCode, insert...
                            org.apache.axis.client.Call _call = createCall();
                            _call.setOperation(_operations[N]);   // N=number generated by WSDL tool
                            _call.setUsername("[username]");     // ADD: inserts username into call
                            _call.setPassword("[password]");     // ADD: inserts password into call
                            _call.setUseSOAPAction(true);

                            // ADD: Pass username/password via wsse cleartext
                            _call.setProperty(WsseClientHandler.PASSWORD_OPTION, 
                                WsseClientHandler.PASSWORD_CLEARTEXT);
                            ...

TestClient.java

The following is a simple test used to show how to call the web services using Java and Apache Axis.

import java.util.Calendar;
                            import gov.ohio.tax.thefinder.OHFinderService.*;

                            public class TestClient {
                            public static void main(String[] args) throws Exception {
                            OHFinderServiceLocator locator = new OHFinderServiceLocator();
                            OHFinderServiceSoap stub = locator.getOHFinderServiceSoap();
                            Calendar cal = Calendar.getInstance();
                            cal.clear();
                            cal.set(2005,0,1);  // Or some other date

                            // Get tax amount for zip
                            ZipCodeReturn resp = stub.getOHSalesTaxByZipCode("[zipcode]", [amount],
                                cal, [true/false]);
                            System.out.println(
                                resp.getTaxResponse().getTaxResponse(0).getTotalSalesTaxAmount());

                            // Get tax amount for address
                            AddressReturn resp2 = stub.getOHSalesTaxByAddress("[address]", "[city]",
                                "OH", "[zipcode]", "US", [amount], cal, [true/false]);
                            System.out.println(
                                resp2.getTaxResponse().getTaxResponse(0).getTotalSalesTaxAmount());
                            }
                            }

Availability and Support

The Finder web service is available 24 hours a day, 7 days a week, except during scheduled maintenance.

Technical support is available Monday through Friday from 8 a.m. to 5 p.m. Eastern Time.

The Ohio Department of Taxation can help with general questions about the web service and high-level implementation issues.

However, we do not provide support for building or developing web services. Developers should have experience working with web services before using this service.

For assistance, email your questions to TheFinderHelp@tax.ohio.gov.

Disclaimer

For sales and use tax purposes, in conformity with the Streamlined Sales Tax Agreement and the Mobile Telecommunications Sourcing Act, vendors and sellers may rely on this information for use in the collection of sales or use tax based on the date used for the search.

By providing this information, neither the State of Ohio nor the Ohio Department of Taxation assumes any liability for any errors or omissions, or in any other respect.

If you feel there is an error or have questions regarding the information you have received, please email the Ohio Department of Taxation at TheFinderHelp@tax.ohio.gov.