Proximity search

Web Services

Proximity search API documentation,

available via HTTP-JSON/XML service.

URL base service:

* API KEY. Same KEY used in maps API js

HTTP requests in GET or POST
Response in JSON / XML format

Get the N nearest points

REQUEST:

Example:

&cmd=prox&mo=42.369140,-3.489919|CENTER&mocs=gdd&rqmolist=%5b40.369140,-3.589919|A%5d,%5b40.367223,-3.583056|B%5d&num=2

Where:

  • mo= Search center, format: lat,lon|ID
  • mocs=gdd Coordinate system (gdd = geographical - lat, long)
  • rqmolist= List of points (coordinates) to be ordered by proximity, in format [lat1,lon1|ID1], [lat2,lon2|ID2], ...
  • rpoicats= (alternative to rqmolist) List of POIs categories (separated by commas) to be searched, ordered by proximity
  • num= Maximum number of points to return (optional)
  • rad= Maximum radius, in meters (optional)

RESPONSE:

<cercalia cmd="prox" version="1">
   <proximity center="-3.4899189461929763,42.36914099810293" num="2" type="mo">
      <molist num="2">
         <mo dist="222546" id="A" pos="1">
            <coord x="-3.5899194036211615" y="40.36914023237501"/>
         </mo>
         <mo dist="222739" id="B" pos="2">
            <coord x="-3.5830562748504877" y="40.36722321688161"/>
         </mo>
      </molist>
   </proximity>
   <server>lb3.cercalia.com</server>
</cercalia>

Where:

  • dist: projected straight-line distance, in meters
  • pos: proximity order (from closest to least)


Get the N nearest points, using routing

REQUEST:

Example:

&cmd=prox&mo=42.369140,-3.489919|CENTRO&mocs=gdd&rqmolist=%5b40.369140,-3.589919|A%5d,%5b40.367223,-3.583056|B%5d&weight=time&num=2

Where:

  • mo= Search center, format: lat,lon|ID
  • mocs=gdd Coordinate system (gdd = geographical - lat, long)
  • rqmolist= List of points (coordinates) to be ordered by proximity, in format [lat1,lon1|ID1], [lat2,lon2|ID2], ...
  • num= Maximum number of points to return (optional)
  • rad= Maximum radius, in meters (optional)
  • weight= route type:
    • time (faster)
    • distance (shortest)
    • money (faster, avoiding tolls)
    • realtime (quickest, considering real time traffic data)
  • iweight=realtime  -> complementary to &weight=.  Use this parameter to obtain the route time, based on the current traffic state, keeping the route path.
  • inverse= If
    • 0 -> route times are from the center to the point list
    • 1 -> route times are from the list of points to the center

 

Routing based on departure time:

  • weight= route type:
    • sptime (quickest, based on departure time)
    • spmoney (quickest, based on departure time and avoiding toll roads)
  • departuretime= departure date and time, in ISO 8601 format. UTC time example:  2019-10-16T07:30:12Z  *Mandatory include &weigt= parameter.


RESPONSE:

<cercalia cmd="prox" version="1">
   <proximity center="-388496,5187633" inverse="0" num="2" type="mo" weight="time">
      <molist num="2">
         <mo dist="222739" id="B" pos="1" routedist="268639" routerealtime="9618936" routetime="9618936" routeweight="9618936">
            <coord x="-398864" y="4891770"/>
         </mo>
         <mo dist="222546" id="A" pos="2" routedist="268238" routerealtime="9637116" routetime="9637116" routeweight="9637116">
            <coord x="-399628" y="4892049"/>
         </mo>
      </molist>
   </proximity>
   <server>http://cercalia-tomcat-lbs-instance4:8080</server>
</cercalia>


Where:

  • dist: projected straight-line distance, in meters.
  • routedist: route distance, in meters.
  • routetime: route time, in milliseconds.


Get the buffer of one or more polylines / polygons, in WKT format

REQUEST:

Call parameters:

&cmd=buffergeoms

GEOMS

List of geometries separated by commas. Each geometry has the following format: [wkt|id]

Where:

wkt: Geometry in wkt format
id: Geometry ID

Accepted geometries:

  • Point
  • PolyLine
  • Polygon
  • MultiPoint

SRS

Coordinates system.

Default: geographical coordinates (EPSG:4326)

BUFFER

Buffer, in meters.

TOLERANCE

Optional. Geometry simplification, in meters (default: 0 meters)

RESPONSE:

Example:

<cercalia cmd="buffergeoms" version="1">
   <buffergeoms>
      <geometry id="1"> POLYGON((-3.708452 40.411246, -3.708434 40.411191, -3.706925 40.411582, -3.705362 40.412022, -3.708362 40.411294, -3.708452 40.411246))</geometry >
      <geometry id="2"> POLYGON((-3.708452 40.411246, -3.708434 40.411191, -3.706925 40.411582, -3.705362 40.412022, -3.708362 40.411294, -3.708452 40.411246))</geometry>
   </buffergeoms>
</cercalia>


Geofencing: Get the points that are within one or more geometries

REQUEST:

Call parameters:

&cmd=insidegeoms

GEOMS

List of geometries separated by commas. Each geometry has the following format: [wkt|id]

Where:

wkt: Polygon geometry in wkt format, or CIRCLE(X Y, radius in meters)
id: Geometry ID

SRS

Coordinates system.

Default: geographical coordinates (EPSG:4326)

MOLIST

List of points, in MO format [x,y|id].

Where:

x,y: point coordinates
id: point ID

MOCS

Coordinates system (MOLIST). Default: EPSG:4326

RESPONSE:

Fer each geometry returns the list of points located insinde. 

Request example:

&cmd=insidegeoms&geoms=[CIRCLE(2.2090 41.4141, 12)|ID1],[CIRCLE(2.3090 41.4141, 5)|ID2]&srs=epsg:4326&molist=[2.2090,41.4141|P1],[2.3090,41.4141|P2]&mocs=gdd


Response:

<cercalia cmd="insidegeoms" version="1">
   <insidegeoms>
      <geometry id=”ID1”> 
         <wkt> CIRCLE(2.2090 41.4141, 12)</wkt>
         <molist num=”1”>
            <mo id=”P1”>
               <coord x=”2.2090” y=”41.4141”>
            </mo>
         </molist>
      </geometry>
      <geometry id=”ID2”> 
         <wkt> CIRCLE(2.3090 41.4141, 5)</wkt>
         <molist num=”1”>
            <mo id=”P2”>
               <coord x=”2.3090” y=”41.4141”>
            </mo>
         </molist>
      </geometry>
   </insidegeoms>
</cercalia>