How to Query the AOC Citation Report Data WS
This document is intended for a user who is tasked with querying the AOC Citation Report Data Web Service. The examples will use raw XML since this is the lowest common denominator for clients and reporting tools.
About the Web Service
The AOC Citation Report Data Web Service was designed to give government entities access to disposed citation data through a secure and flexible channel for reporting purposes.
How to make queries
The best way to understand how to make your own queries is to understand an example query and how the web service processes it. This section walks through an example using the DATERANGE procedure.
A client (reporting tool) will make a data request to the web service by providing a userID, password, procedureName, some parameters, and the needed fields.
Here is an example request:
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns2="http://reportdata.ws.cdx.gaaoc.us/" > <soap:Header> <ns2:RequestHeader > <UserID>test_user</UserID> <Password>pass</Password> </ns2:RequestHeader> </soap:Header> <soap:Body> <ns2:CitationDataRequest> <DataRequest> <procedureName>DATERANGE</procedureName> <fields>EXPRESS_CITATION_ID</fields> <fields>CITATION_DATE</fields> <parameters>03/01/2010</parameters> <parameters>05/31/2010</parameters> </DataRequest> </ns2:CitationDataRequest> </soap:Body> </soap:Envelope>
I'll break down how this request is handled by the web service. First the UserID and Password is evaluated. The Web service tries to locate a user with these credentials and if it finds one processing continues if not an “Invalid user and/or password” error is passed back.
Next the fields are verified by making sure that they are listed in the list of available fields. One can view this at https://express.gaaoc.us/cdxReportDataWS/reportData/ListAvailableFields. The first field can contain the value "ALL" or "ALL_EXCEPT". "ALL" will return all fields. "ALL_EXCEPT" will create a list of all fields and then remove the remaining provided fields from the list. If any of the fields do not meet these criteria an error will be passed back explaining which fields were problematic.
Use of “ALL” and “ALL_EXCEPT” should only be needed in very rare circumstances. Please explicitly request the fields that your application needs. This will minimize bandwidth and server load.
Next the procedureName is validated. The procedure must come from the list of available procedures. This is viewable by visiting this link https://express.gaaoc.us/cdxReportDataWS/reportData/ListAvailableProcedures. If the procedure is not in the list an error is returned.
Next the web service makes sure that the given number of parameters is equal to the number of parameter descriptions in the procedure. If you look at date range in the available procedures list you will notice it has 2 parameter descriptions:
In this case 2 parameters must be given or an error will be sent back.
Next the parameters are validated for format. For the date range procedure the first and second parameter must be in MM/DD/YYYY format or an error will be sent back.
Now that validation has completed the web service will make a query to the database based on the citation request and the results will be returned. Here is an example response:
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"> <soap:Body> <ns2:CitationDataRequestResponse xmlns:ns2="http://reportdata.ws.cdx.gaaoc.us/"> <CitationData> <EXPRESS_CITATION_ID>81</EXPRESS_CITATION_ID> <CITATION_DATE>2010-03-02-05:00</CITATION_DATE> </CitationData> <CitationData> <EXPRESS_CITATION_ID>83</EXPRESS_CITATION_ID> <CITATION_DATE>2010-05-02-04:00</CITATION_DATE> </CitationData> <CitationData> <EXPRESS_CITATION_ID>82</EXPRESS_CITATION_ID> <CITATION_DATE>2010-04-02-04:00</CITATION_DATE> </CitationData> </ns2:CitationDataRequestResponse> </soap:Body> </soap:Envelope>
You can see that 3 records were returned that are in the date range 03/01/2010 - 05/31/2010 with the two specified fields EXPRESS_CITATION_ID and CITATION_DATE.