Overview

All features of the framework can be accessed via a RESTful API. Note that this developer zone is a play ground to experiment and test the framework. This hosted API is not designed to be a SaaS. As such we do not guaranty any uptime. We provide a test API KEY but please limit the maximum number of transactions to 5000 per day. You can get your own API KEY by signing up. If you would like to use this API in production, you will need to self-host and install the software (a packaged micro service) on your own servers.

The generic format of all http REST request will be have the following pattern:

GET http://api.stratomaps.com/[end-point]?[your-api-key]&[parameter1]&[parameter2]&...

where
  • [your-api-key] is the api-key you got after signing up.
  • [end-point] is one of the available end-point.
  • [parameter] is a mandatory or optional parameter. Mandatory or optional parameters will vary for each end-point.
For testing online you can use the following API KEY (maximum 5000 transactions per day): WVU1e2Qy4O

Request example with the reverse (Reverse Geocoding) end-point:
GET http://api.stratomaps.com/reverse?apikey=YOUR-KEY&latlon=48.860871,2.350570

Response will be presented as a JSON:
{ 
  "id":2083,  //unique id generated by server
  "distance":"9.25",  //projected distance in meters from input latlon
  "tag":[  //key,value pairs. Will return information about closest road segment
    {"k":"bicycle","v":"yes"},
    {"k":"name","v":"Rue Quincampoix"},
    {"k":"maxspeed","v":"15"},
    {"k":"access:motorcar","v":"destination"},
    {"k":"highway","v":"pedestrian"},
    {"k":"oneway","v":"yes"}
  ],
  "addrtag":[  //key,value pairs. Will return information about address
    {"k":"addr:housenumber","v":"41"},
    {"k":"addr:country","v":"FR"},
    {"k":"source","v":"cadastre-dgi-fr source : Direction Générale des Impôts - Cadastre ; mise à jour : 2010"},
    {"k":"addr:street","v":"Rue Quincampoix"},
    {"k":"addr:city","v":"Paris"}
  ],
  "status":"success",
  "copyright":"© OpenStreetMap contributors (http://www.openstreetmap.org)",
  "license":"Open Database License",
  "projectedLL":"48.860896,2.350449"  //reverse geocode latlon
}
      


Reverse Geocoding

The reverse geocoder let you specify a geographic position and get back the closest road feature that meets your search criteria. The response will contain the reverse geocoded position along with all attributes as encoded into the OSM data. By default we return all attributes as key,value pairs (k,v). The naming of the keys, values strictly follow the way the data is encoded. More details on the OSM tags can be found at http://wiki.openstreetmap.org/wiki/Map_Features. In addition we perform interpolation to the closest point address from the projected position.

Reverse Geocoding end-point parameters:

GET http://api.stratomaps.com/reverse?[required_parameters]&[optional_parameters]
where
[required_parameters]
apikey apikey=WVU1e2Qy4O

This is a test API KEY. You can get your own API KEY by signing up.
latlon latlon=44.841504,-0.575094

A position (latitude, longitude) in decimal degree. The position should be provided in WGS84 coordinate system. Make sure the position falls in an area where data has been loaded. See Data Coverage.
With a proper key, you can copy and paste the following request into the browser's url:
http://api.stratomaps.com/reverse?apikey=YOUR-KEY&latlon=48.860871,2.350570
[optional_parameters]
customid customid=12345

CustomID lets you associate requests to a unique ID. CustomID simply echos back whatever string you pass in the request.
radius radius=50

Radius limit the search for features to the specified value. By default it is set to 100 meters. The integer value is interpreted as meters. For now we have limited the maximum radius you can set to 250 meters.
heading heading=45

This is the asset (vehicle) heading as provided by the GPS. This parameters greatly help to snap to the right road feature (geometries with a bearing within tolerance from vehicle heading), especially in dense area with complex crossing. It can also be used in combination with radius to limit the search area. The angle is expressed in degrees from 0 to 360 degrees counter clockwise. North is 0, west is 90, south 180 etc. Negative numbers can be used as well e.g. -45 degrees from the 0 north.
headingtolerance headingtolerance=20

Heading tolerance set the angle precision arround the heading. If heading tolreance is 20 and heading is 45, the snap to closest road features will be done between andle 25 and 65. Default heading tolerance is 15 degrees.
clockwise clockwise=false

Clockwise defines if the heading provided as input should be considered clockwise or anti-clockwise starting from 0 degree (north). Values supported for this parameter:
  • true
  • false
Set to false by default.
vehicle vehicle=car

Vehicle parameter let you specify the vehicle type. By default there is no type. The reverse geocoder will snap to all roads (motorway, primary, residential, etc). Setting the vehicle type filters the results to the roads where the choosen vehicle can navigate. The current supported vehicle types are:
  • all
  • car
  • pedestrian
  • bicycle
  • train
  • subway
  • bus
maxspeed maxspeed=30

Maxspeed filters the results to only return roads for which the road posted speed is greater or equal than the provided maxspeed parameter. Note that road where no posted max speed data exists will be ignored.
customfilter customfilter=bicycle::yes

Custom filter lets you specify you own key,value pair. This implies you have an understanding of the underlying data. You can specify multiple key,val pairs in one request. Note that this parameter cannot be used in conjunction with the vehicle parameter. However this can be achieved by the specific key,val pairs.
address address=true

The address parameter let you specify if you want the reverse geocoder to search for point address and present the output in the result. Note that point address may not be always present in the data. Values supported for this parameter:
  • true
  • false
Set to false by default.
A few requests to illustrate the use of some of the optional parameters described above:

Simple snap with and without point address
http://api.stratomaps.com/reverse?apikey=YOUR-KEY&latlon=48.865021,2.352147
http://api.stratomaps.com/reverse?apikey=YOUR-KEY&latlon=48.865021,2.352147&address=true
Same latlon snap on "Boulevard de Sébastopol" or "Rue Greneta" based on vehicle heading and radius
http://api.stratomaps.com/reverse?apikey=YOUR-KEY&latlon=48.865123,2.352241&heading=-20&radius=50
http://api.stratomaps.com/reverse?apikey=YOUR-KEY&latlon=48.865123,2.352241&heading=100&radius=50
Only snap to a road where he max autorized speed is less than 70kmh.
http://api.stratomaps.com/reverse?apikey=YOUR-KEY&latlon=48.893290,2.303493&maxspeed=70
Same latlon snap on two different roads based on provided vehicle type
http://api.stratomaps.com/reverse?apikey=YOUR-KEY&latlon=48.856734,2.341279&vehicle=car
http://api.stratomaps.com/reverse?apikey=YOUR-KEY&latlon=48.856734,2.341279&vehicle=pedestrian
Snap to closest road which has sidewalks on both side and are lit
http://api.stratomaps.com/reverse?apikey=YOUR-KEY&latlon=48.864404,2.331050&customfilter=sidewalk::both,lit::yes

Batch Reverse Geocoding

For better performances, many reverse geocoding requests can be performed as one single batch request. One single http POST request will contains many reverse geocodes queries. These queries will be encapsulated within a JSON object and sent to the API. The API will respond at once with the results of all of the queries.

Important:

  • the HTTP method must be POST
  • the HTTP request Content-Type header must be set to application/json

Batch Reverse Geocoding end-point parameters:
POST URL:
http://api.stratomaps.com/reverse?apikey=YOUR-KEY
Content/Type:
application/json
POST Body:
{
  "batchid":"154",
  "vehicle":"car",
  "clockwise":"false",
  "positions":[
    "latitude,longitude,radius,heading,heading tolerance,speed,id",
    ...
  ]
}

where
[required_parameters]
apikey
(in the URL)
apikey=WVU1e2Qy4O

This is a test API KEY. You can get your own API KEY by signing up.
latitude,longitude latlon=44.841504,-0.575094 A position (latitude, longitude) in decimal degree. The position should be provided in WGS84 coordinate system. Make sure the position falls in an area where data has been loaded. See Data Coverage.
[optional_parameters]
batchid A custom id for the entire batch request. Provided by the end user.
vehicle vehicle=car

Vehicle parameter let you specify the vehicle type. By default there is no type. The reverse geocoder will snap to all roads (motorway, primary, residential, etc). Setting the vehicle type filters the results to the roads where the choosen vehicle can navigate. The current supported vehicle types are:
  • all
  • car
  • pedestrian
  • bicycle
  • train
  • subway
  • bus
clockwise Specifies if the headings provided for the requests are to be considered as clockwise or anti-clockwise. 0 degree being north.
radius radius=50

Radius limit the search for features to the specified value. By default it is set to 100 meters. The integer value is interpreted as meters. For now we have limited the maximum radius you can set to 250 meters.
heading heading=45

This is the asset (vehicle) heading as provided by the GPS. This parameters greatly help to snap to the right road feature (geometries with a bearing within tolerance from vehicle heading), especially in dense area with complex crossing. It can also be used in combination with radius to limit the search area. The angle is expressed in degrees from 0 to 360 degrees counter clockwise. North is 0, west is 90, south 180 etc. Negative numbers can be used as well e.g. -45 degrees from the 0 north.
headingtolerance headingtolerance=20

Heading tolerance set the angle precision arround the heading. If heading tolreance is 20 and heading is 45, the snap to closest road features will be done between andle 25 and 65. Default heading tolerance is 15 degrees.
maxspeed maxspeed=30

Maxspeed filters the results to only return roads for which the road posted speed is greater or equal than the provided maxspeed parameter. Note that road where no posted max speed data exists will be ignored.
customid A custom id that uniquely identifies a given request within a batch of requests.
An example of a Body POST with 5 reverse geocodes:
{  
  "batchid":"154",
  "vehicle":"car",
  "clockwise":"false",
  "positions":[
    "51.48544456,0.00102378,20,75,15,75,1001",
    "51.56212236,-0.11707784,,,,,1002",
    "51.50129372,-0.23810773,,,,,1003",
    "51.50561953,-0.25401589,5,,,,1004",
    "51.48952289,-0.0257211,,40,,,1005"
  ]
}

GPX Map Matching

If you have tracks of GPS positions, you can map match them to the road network using the /gpx end point. The GPX needs to be compliant with the GPX scpecification. More details can be found there. Please note that only map matching against trkpt is performed. Course (vehicle bearing) can be taken into account to improve map matching accuracy. Heading tolerance as well as radius can also be set. Finally for third party application that wants to perform location analysis (give spatial context), setting verbose to "true" will output road network attributes for each map matched section.

Important:

  • the HTTP method must be POST
  • the HTTP request Content-Type header must be set to form-data

GPX Map Matching end-point parameters:
POST URL:
http://api.stratomaps.com/gpx?apikey=YOUR-KEY
Content/Type:
form-data
Key/Value:
key='file'
value=path/to/your/file
where
[required_parameters]
apikey apikey=WVU1e2Qy4O

This is a test API KEY. You can get your own API KEY by signing up.
[optional_parameters]
radius radius=50

Radius limit the search for features to the specified value. By default it is set to 100 meters. The integer value is interpreted as meters. For now we have limited the maximum radius you can set to 250 meters.
headingtolerance headingtolerance=20

Heading tolerance set the angle precision arround the heading. If heading tolreance is 20 and heading is 45, the snap to closest road features will be done between andle 25 and 65. Default heading tolerance is 15 degrees.
clockwise clockwise=false

Clockwise defines if the heading provided as input should be considered clockwise or anti-clockwise starting from 0 degree (north). Values supported for this parameter:
  • true
  • false
Set to false by default.
vehicle vehicle=car

Vehicle parameter let you specify the vehicle type. By default there is no type. The reverse geocoder will snap to all roads (motorway, primary, residential, etc). Setting the vehicle type filters the results to the roads where the choosen vehicle can navigate. The current supported vehicle types are:
  • all
  • car
  • pedestrian
  • bicycle
  • train
  • subway
  • bus
verbose verbose=false

Adding verbose=true to the request will add a <cmt> element to the generated gpx for each map matched position. The <cmt> element includes all attributes available for the map matched road section. Values supported for this parameter:
  • true
  • false
Set to false by default.
The following in.gpx file is manually generated by GPSVisualizer draw tool kindly made available online by GPSVisualizer

in.gpx :        

<?xml version="1.0" encoding="UTF-8"?>
  <gpx version="1.1" creator="GPS Visualizer Sandbox http://www.gpsvisualizer.com/draw/" 
       xmlns="http://www.topografix.com/GPX/1/1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
       xsi:schemaLocation="http://www.topografix.com/GPX/1/1 http://www.topografix.com/GPX/1/1/gpx.xsd">
    <trk>
      <name></name>
      <desc>Length: 0.271 km (0.168 mi)</desc>
      <trkseg>
        <trkpt lat="48.8539080" lon="2.3448676"></trkpt>
        <trkpt lat="48.8546069" lon="2.3450500"></trkpt>
        <trkpt lat="48.8548681" lon="2.3456615"></trkpt>
        <trkpt lat="48.8555246" lon="2.3459029"></trkpt>
        <trkpt lat="48.8559376" lon="2.3464930"></trkpt>
      </trkseg>
    </trk>
  </gpx>

out.gpx (after map matching to the road network) :

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<gpx xmlns="http://www.topografix.com/GPX/1/1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
     creator="GPS Visualizer Sandbox http://www.gpsvisualizer.com/draw/" version="1.1" 
     xsi:schemaLocation="http://www.topografix.com/GPX/1/1 http://www.topografix.com/GPX/1/1/gpx.xsd">
  <metadata>
    <copyright>
      <license>© OpenStreetMap contributors (http://www.openstreetmap.org)</license>
    </copyright>
  </metadata>
  <trk>
    <name/>
    <desc>Length: 0.271 km (0.168 mi)</desc>
    <trkseg>
      <trkpt lat="48.854041" lon="2.344579"/>
      <trkpt lat="48.854568" lon="2.345136"/>
      <trkpt lat="48.854933" lon="2.345519"/>
      <trkpt lat="48.855487" lon="2.346017"/>
      <trkpt lat="48.855977" lon="2.346347"/>
    </trkseg>
  </trk>
</gpx>

The following images shows the GPX before and after GPX Map Matching:
in.gpx out.gpx
It is also possible using the "&verbose=true" option to get information about the each map matched section: <?xml version="1.0" encoding="UTF-8" standalone="no"?> <gpx xmlns="http://www.topografix.com/GPX/1/1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" creator="GPS Visualizer Sandbox http://www.gpsvisualizer.com/draw/" version="1.1" xsi:schemaLocation="http://www.topografix.com/GPX/1/1 http://www.topografix.com/GPX/1/1/gpx.xsd"> <metadata> <copyright> <license>© OpenStreetMap contributors (http://www.openstreetmap.org)</license> </copyright> </metadata> <trk> <name/> <desc>Length: 0.271 km (0.168 mi)</desc> <trkseg> <trkpt lat="48.854041" lon="2.344579"> <cmt> {"k":"busway:left","v":"opposite_lane"},{"k":"cycleway:right","v":"share_busway"}, {"k":"name","v":"Pont Saint-Michel"},{"k":"busway:right","v":"lane"}, {"k":"bridge","v":"yes"},{"k":"wikipedia","v":"fr:Pont Saint-Michel"}, {"k":"highway","v":"primary"},{"k":"cycleway:left","v":"share_busway"}, {"k":"layer","v":"1"},{"k":"oneway","v":"yes"} </cmt> </trkpt> <trkpt lat="48.854568" lon="2.345136"> <cmt> {"k":"name:ru","v":"бульвар Пале"},{"k":"note","v":"Voies de bus+vélo dans les 2 sens"}, {"k":"busway:left","v":"opposite_lane"},{"k":"cycleway:right","v":"share_busway"}, {"k":"oneway:bicycle","v":"no"},{"k":"name","v":"Boulevard du Palais"}, {"k":"busway:right","v":"lane"},{"k":"highway","v":"primary"}, {"k":"cycleway:left","v":"share_busway"},{"k":"oneway","v":"yes"} </cmt> </trkpt> <trkpt lat="48.854933" lon="2.345519"> <cmt> {"k":"name:ru","v":"бульвар Пале"},{"k":"note","v":"Voies de bus+vélo dans les 2 sens"}, {"k":"busway:left","v":"opposite_lane"},{"k":"cycleway:right","v":"share_busway"}, {"k":"oneway:bicycle","v":"no"},{"k":"name","v":"Boulevard du Palais"}, {"k":"busway:right","v":"lane"},{"k":"highway","v":"primary"}, {"k":"cycleway:left","v":"share_busway"},{"k":"oneway","v":"yes"} </cmt> </trkpt> <trkpt lat="48.855487" lon="2.346017"> <cmt> {"k":"name:ru","v":"бульвар Пале"},{"k":"note","v":"Voies de bus+vélo dans les 2 sens"}, {"k":"busway:left","v":"opposite_lane"},{"k":"cycleway:right","v":"share_busway"}, {"k":"oneway:bicycle","v":"no"},{"k":"name","v":"Boulevard du Palais"}, {"k":"busway:right","v":"lane"},{"k":"highway","v":"primary"}, {"k":"cycleway:left","v":"share_busway"},{"k":"oneway","v":"yes"} </cmt> </trkpt> <trkpt lat="48.855977" lon="2.346347"> <cmt> {"k":"name:ru","v":"бульвар Пале"},{"k":"note","v":"Voies de bus+vélo dans les 2 sens"}, {"k":"busway:left","v":"opposite_lane"},{"k":"cycleway:right","v":"share_busway"}, {"k":"oneway:bicycle","v":"no"},{"k":"name","v":"Boulevard du Palais"}, {"k":"busway:right","v":"lane"},{"k":"highway","v":"primary"}, {"k":"cycleway:left","v":"share_busway"},{"k":"oneway","v":"yes"} </cmt> </trkpt> </trkseg> </trk> </gpx>


Proximity Search

Coming soon. In the process of implementing a proximity end-point so that you can find the closest assets within radius against OSM and custom pre-loaded data


Add Custom Data

A custom end point will soon be available to let you import and/or modify your own data points on the fly. Please note that this will be available only using a self-hosted version of the software.


Data Coverage

The table below list the cities currently loaded onto our servers alongside with data provider and freshness timestamp. If you wish us to add one specific region to support your testing, please contact us. We will be happy to add new regions.

AFRICA
Cape Town OpenStreetMap 01/11/2016
Johannesburg OpenStreetMap 01/11/2016
EUROPE
Amsterdam OpenStreetMap 01/11/2016
Bordeaux OpenStreetMap 01/11/2016
London OpenStreetMap 01/11/2016
Monaco OpenStreetMap 01/11/2016
Moscow OpenStreetMap 01/11/2016
Munich OpenStreetMap 01/11/2016
Paris OpenStreetMap 01/11/2016
NORTH AMERICA
New York OpenStreetMap 01/11/2016

DMCA.com Protection Status