README.mdown_old

#POIProxy

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

[![](http://poiproxy.mapps.es/poiproxy_logo.png)](http://poiproxy.mapps.es)

##The idea

The idea was taken from a [GSoC project for gvSIG Mini][gsoc_idea], 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.

[![](http://poiproxy.mapps.es/poiproxy_diagram.png)](http://poiproxy.mapps.es)

##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][tiles_google].

     `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][tiles_google].

     `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 `callback`to 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 <a href="http://www.jarvana.com/jarvana/view/es/prodevelop/es.alrocar.poiproxy/1.0.1/es.alrocar.poiproxy-1.0.1-javadoc.jar!/index.html">here</a> 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.

[![](https://confluence.prodevelop.es/download/attachments/22249524/socialservicecomponents.png)](https://confluence.prodevelop.es/download/attachments/22249524/socialservicecomponents.png)

##Sequence diagram

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

[![](https://confluence.prodevelop.es/download/attachments/22249524/socialservicesequence.png)](https://confluence.prodevelop.es/download/attachments/22249524/socialservicesequence.png)

[gsoc_idea]: https://confluence.prodevelop.es/display/GVMN/Design+and+implement+an+API+for+tiled+vectorial+support+of+geo-location+data+services
[tiles_google]: http://www.maptiler.org/google-maps-coordinates-tile-bounds-projection/

##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:

<pre><code>
{
    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"
                    }
     }
}
</pre></code>

* **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.

[![](http://www.alrocar.es/img/gvsigmini_poiproxy2.png)](http://www.alrocar.es/img/gvsigmini_poiproxy2.png)

* ***POIProxy and Leaflet***

There's a <a href="http://poiproxy.mapps.es/demo/index.html">demo of POIProxy</a> running on <a href="http://leaflet.cloudmade.com/">Leaflet</a> 

* ***POIProxy and OpenLayers***

<a href="https://github.com/jacarma/olsocial">jacarma</a> has implemented a new OpenLayers Layer to load POIProxy services. 

You can see a demo <a href="https://github.com/jacarma/olsocial">here</a>

##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