POIProxy: A Java repository from iwek

#POIProxy

POIProxy is a service to retrieve Points of Interest from any public POI service such as Foursquare, Twitter, Buzz, Panoramio, Wikipedia, Flickr, etc...

##The idea

The idea was taken from a GSoC project for gvSIG Mini, but has evolved to a standalone public service available at http://poiproxy.mapps.es

The main purpose is to have a single service that handles requests to any public POI service providing a well defined REST API. POIProxy is able to parse JSON and XML responses and serve standard GeoJSON format. Finally it has the capability to add new services by providing a configuration file.

##API

Get available services

Returns the available services registered into POIProxy and their description

http://poiproxy.mapps.es/describeServices
Browse by tile

Returns the points inside the given tile (Z/X/Y). The tile notation is the same as Google Maps uses.

http://poiproxy.mapps.es/browse?service=XXX&z=0&x=0&y=0&callback=whatever
Browse by extent

Returns the points inside the given bounding box. The coordinate reference system is EPSG:4326

http://poiproxy.mapps.es/browseByExtent?service=XXX&minX=-0.376&minY=39.47&maxX=-0.37&maxY=39.48&callback=whatever
Browse by lon,lat and distance

Returns the points inside a given radius distance of a point. The coordinate reference system is EPSG:4326

http://poiproxy.mapps.es/browseByLonLat?service=XXX&lon=-0.38&lat=39.46&dist=500&callback=whatever
Search by tile

Returns the points inside the given tile (Z/X/Y) for the given query. The tile notation is the same as Google Maps uses.

http://poiproxy.mapps.es/browse?service=XXX&z=0&x=0&y=0&query=search_term&callback=whatever
Search by extent

Returns the points inside the given bounding box for the given query. The coordinate reference system is EPSG:4326

http://poiproxy.mapps.es/browseByExtent?service=XXX&minX=-0.376&minY=39.47&maxX=-0.37&maxY=39.48&query=search_term&callback=whatever
Search by lon,lat and distance

Returns the points inside a given radius distance of a point for the given query. The coordinate reference system is EPSG:4326

http://poiproxy.mapps.es/browseByLonLat?service=XXX&lon=-0.38&lat=39.46&dist=500&query=search_term&callback=whatever

POIProxy supports JSONP by adding the parameter callbackto any request. If not provided then a JSON response is returned.

IMPORTANT: Not all services registered in POIProxy support all the API requests. Please refer to the describeServices operation to see the list of available operations per registered service.

Javadocs

Check here the javadocs of the library

##Projects

POIProxy is composed by 4 projects:

es.alrocar.poiproxy

Is the main POIProxy library implementation.
es.alrocar.poiproxy.rest

A REST interface of POIProxy to be deployed into a servlet container
es.alrocar.poiproxy.gae

A REST interface of POIProxy to be deployed into Google App Engine
es.alrocar.map.vector

A Java vectorial provider, to access the POIProxy from your application. It's being used by gvSIG Mini to load POI layers provided by POIProxy.

##Building a workspace of POIProxy

Just clone this repository git clone https://github.com/alrocar/POIProxy, import the projects into an Eclipse workspace and run from the root directory:

mvn eclipse:eclipse

mvn clean install

Finally refresh the workspace

##Running POIProxy

In a servlet container

To run POIProxy in a servlet container (i.e. Jetty) at localhost:

cd es.alrocar.poiproxy.rest

mvn jetty:run

The server will be up at http://localhost:8080

Note: The services configuration should be located at: /var/lib/sp/services

In Google App Engine

To run POIProxy in Google AppEngine (at localhost):

cd es.alrocar.poiproxy.gae

mvn gae:unpack

mvn gae:run

The server will be up at http://localhost:8080

Both projects depend on es.alrocar.poiproxy that is deployed at maven central and should be downloaded automatically to your local maven repository.

##Deploying POIProxy

In a servlet container

To deploy POIProxy in a servlet container (i.e. Tomcat), generate a war and publish it in the servlet container:

mvn war:war

Note: The services configuration should be located at: /var/lib/sp/services

In Google App Engine

To deploy POIProxy in Google AppEngine run:

mvn gae:deploy

Note: You should configure your own AppEngine instance

##Components diagram

This diagram shows a typical scenario of a client application that consumes POIProxy.

##Sequence diagram

This diagram shows the internal collaboration among classes in the POIProxy library and a client application

##Describe service specification

POIProxy provides a parsing framework that enables supporting new services by just providing a configuration file of the service.

A service configuration file, is a json formatted file like this:


{
    format: "xml",
    apiKey : "",
    requestTypes : {
                    "browse": {"url": "http://wfs.prodevelop.es/geoserver/wfs?TYPENAME=world%3Acities&SERVICE=WFS&VERSION=1.0.0&REQUEST=GetFeature&SRS=EPSG%3A4326", "params": []},
                    "search": {"url": "b", "params": []}
                    },
    featureTypes : { "browse" : {
                         "feature" : "featureMember",
                    	"elements" : ["City", "Country"],
                    	"lon": "longitude", 
                    	"lat": "latitude"
                    },"search" : {
                    	"feature" : "kind",
                    	"elements" : ["title", "published", "name", "profileUrl", "thumbnailUrl"],
                    	"lon": "lng", 
                    	"lat": "lat"
                    }
     }
}

format: The format of the original response from the source server. Currently supported formats are "xml" and "json".
apiKey: Not used
requestTypes: It's an object that describes two types of requests, "browse" or "search". For each request type it's enough with describing the "url". For the param substition in the URL there are several wildcards defined: _MINX_, _MINY_, _MAXX_, _MAXY_, _LAT_, _LON_, _DIST_, _QUERY_. You should add these wildcards properly inside the URL so the POIProxy can substitute them properly.
featureTypes: An object describing the type of the response of the source service. It's used to parse complex objects into plain GeoJSON objects.
- feature: The property defining a new POI. It should be the first property in the source response document to identify a new POI.
- elements: A list of properties to be parsed.
- lon: The longitude attribute in the source response document.
- lat: The latitude attribute in the source response document.

##Use cases

POIProxy and gvSIG Mini

It's still a proof of concept, but current development version of gvSIG Mini is able to browse POIProxy layers.

POIProxy and Leaflet

There's a demo of POIProxy running on Leaflet

POIProxy and OpenLayers

jacarma has implemented a new OpenLayers Layer to load POIProxy services.

You can see a demo here

##License and Contact

POIProxy is free software and is released under GNU LGPL Version 2 (or any later version). Please read carefully the Terms of service of the different services supported and use your own API keys when apply.

If you have any question, want to add a new service, etc. you can contact at:

mapps@mapps.es

iwek/POIProxy

Javadocs