This is a Java language binding (wrapper) to the Open311 GeoReport v2 REST API (current version: 0.0.4
). You can check the library site if you want to check the javadocs, test coverage, etc.
The main features are:
If you find any problem or miss any feature, just open an issue.
If you are interested about new features or the development process please check this blog.
The easiest way to start using the library is to add the dependency to your project dependency manager system. The library is currently avaliable in the Maven central repository, which makes it compatible with tools such as:
Below, an example using Maven.
<dependency>
<groupId>org.codeforamerica.open311</groupId>
<artifactId>jreport</artifactId>
<version>0.0.4</version>
</dependency>
There are many links in the Maven central repository page, and you can find the .jar
file (with its sources and javadocs). Please, note that this .jar
does not contains its dependencies, so it will not work unless you attach them too.
In order to compile and test this project you should have Maven installed in your system.
# Clone this repository
git clone https://github.com/codeforamerica/open311_java.git
cd open311_java
# The following commands are independent. Execute which you need (probably the last one).
# Compile the project (and download dependencies)
mvn compile
# Execute tests
mvn test
# Execute tests with cobertura analysis
mvn cobertura:cobertura
# Generate the .jar without dependencies
mvn package
# Generate the .jar with dependencies
mvn assembly:assembly
You may have problems if you are using an old version of git
since one of the executed commands is git clone --recursive
and it doesn't work with its oldest versions. Please, update your git
in that case.
mvn cobertura:cobertura
will write its output in target/site/cobertura/
, open the index.html
file to check it.mvn package
will output the target/jreport-{version}.jar
file.mvn assembly:assembly
will output the target/jreport-{version}-jar-with-dependencies.jar
file.You will need the APIWrapperFactory in order to build the APIWrapper (which will allow you to query the endpoint). There are two different ways of creating the factory:
// From the city (EndpointType.PRODUCTION is selected by default)
APIWrapper wrapper = new APIWrapperFactory(City.SAN_FRANCISCO).build();
// From the city, test endpoint.
APIWrapper wrapper = new APIWrapperFactory(City.SAN_FRANCISCO, EndpointType.TEST).build();
// From the url of the endpoint
APIWrapper wrapper = new APIWrapperFactory("https://www.myendpointurl.com/").build();
// From the url of the endpoint, the jurisdiction_id, and the data interchange format
APIWrapper wrapper = new APIWrapperFactory("https://www.myendpointurl.com/",
"myjurisdictionId", Format.JSON).build();
// With the api key
wrapper = new APIWrapperFactory(City.SAN_FRANCISCO).setApiKey("your api key").build();
// Without caching data and the api key
wrapper = new APIWrapperFactory(City.SAN_FRANCISCO).setCache(new NoCache()).
setApiKey("your api key").build();
Check all the possible parameters and constructors of the APIWrapperFactory
in its documentation page.
// GET service list
List<Service> listOfServices = wrapper.getServiceList();
// GET service definition
ServiceDefinition definition = wrapper.getServiceDefinition("serviceCode");
// POST service request
POSTServiceRequestResponse response = wrapper.postServiceRequest(
new POSTServiceRequestData("serviceCode", addressId, listOfattributes));
// GET service_request_id from a token
ServiceRequestIdResponse serviceRequestIdresponse =
wrapper.getServiceRequestIdFromToken("token");
// GET service requests
List<ServiceRequest> serviceRequests = wrapper.getServiceRequests(
new GETServiceRequestsFilter().setStatus(Status.OPEN));
// GET service request
ServiceRequest serviceRequest = wrapper.getServiceRequest("serviceRequestId");
It is worth it to check the documentation and find all the possible parameters of the GETServiceRequestFilter
and POSTServiceRequestData
classes.
This library tries to save some responses for a certain time in order to avoid expensive network operations.
factory = new APIWrapperFactory().setCache(new NoCache());
factory = new APIWrapperFactory().setCache(AndroidCache.getInstance(getApplicationContext()));
factory = new APIWrapperFactory().setCache(new YourCacheImplementation());
In case you want to delete the cache:
wrapper.getCache().delete()
RegularJavaCache.getInstance().delete()
AndroidCache.getInstance(getApplicationContext()).delete()
Please, note that when you delete the cache you will delete ALL the cached data.
Some of the endpoints could have SSL certificates which signature won't be recognize by Java. Up to now, the HTTP client used by this library ignores those certificate signature problems so it is your responsibility to make sure that you are providing a secure url.