Skip to content
This repository

A proxy service to retrieve POIs from several public services (Nominatim, Mapquest, Cloudmade, Geonames, Panoramio, Ovi, Flickr, Twitter, LastFM, Wikipedia, Youtube, Minube, Buzz, Foursquare, Gowalla, ...)

README.mdown

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

Something went wrong with that request. Please try again.