Migrate geospatial filter parameters

All geospatial filters are specified using the same in parameter in Traffic API v7. This is a change from Traffic API v6, where a single geospatial parameter had to be specified out of a selection of four.

Circle (Proximity)

Traffic API v6: prox={latitude},{longitude},{radius} Traffic API v7: in=circle:{latitude},{longitude};r={radius}

The radius is measured in meters in both cases.

Traffic API v6 example: prox=52.537675,13.40302,1000 Traffic API v7 example: in=52.537675,13.40302;r=1000

Bounding Box

  • Traffic API v6: bbox={south-west latitude},{south-west longitude};{north-east latitude},{north-east longitude}
  • Traffic API v7: in=bbox:{west longitude},{south latitude},{east longitude},{north latitude}

Note

The Traffic API v7 uses the GeoJSON standard to define a bounding box, which defines the latitude and longitude in the opposite order from that used in v6.

  • Traffic API v6 example: `bbox=52.527129,13.386969;52.549420,13.424134``
  • Traffic API v7 example: in=bbox:13.386969,52.527129,13.424134,52.549420

Corridor

  • Traffic API v6: corridor={latitude1},{longitude1};{latitude2},{longitude2};...;{width}
  • Traffic API v7: in=corridor:{polyline};r={radius}

The width and radius values are measured in meters, with width being twice the radius.

  • Traffic API v6 example: corridor=52.529583,13.379416;52.532820,13.399157;52.538458,13.395896;52.541277,13.408856;52.539085,13.424048;230
  • Traffic API v7 example: in=corridor:BG-6kmkDw1zwZqqG6xmBsgL5rGmwFgqZ_oEw1d;r=230

Tile address

A tile address refers to a specific tile with an address in the form Z/X/Y, where Z is the zoom and X and Y are the column and row indices respectively. Tile addresses are based on the Mercator Projection.

  • Traffic API v6: Z/X/Y
  • Traffic API v7: in=bbox:{west longitude},{south latitude},{east longitude},{north latitude}

The tile address must be converted to a bounding box. See Convert tile address to bounding box for more information.

  • Traffic API v6 example: 12/2200/1343
  • Traffic API v7 example: in=bbox:13.359375,52.482780,13.447266,52.536273

Convert tile address to bounding box

In order to build a request for a tile, the tile address must be converted to a bounding box for that tile. The conversion algorithm is found in the following code sample:

JavaScript
/** Convert a tile address to the bounding box for that tile
 *
 * @param {number} zoom - Zoom level, integer from 1 to 17
 * @param {number} x - Column index in tile grid
 * @param {number} y - Row index in tile grid
 *
 * @returns {Object} Bounding box is an object with keys for each of the 4
 * bounds west longitude, south latitude, east longitude, and north latitude
 */
function tile_to_bbox(zoom, x, y) {
    var n = 1;
    if (zoom > 0) {
        n = 2 << (zoom - 1);
    }

    function x_tile_to_lng(x, n) {
        return (x / n * 360.0) - 180.0;
    }

    function y_tile_to_lat(y, n) {
        return Math.atan(Math.sinh(Math.PI * (1 - 2 * y / n))) * 180 / Math.PI;
    }

    var west = x_tile_to_lng(x, n);
    var south = y_tile_to_lat(y + 1, n);

    var east = x_tile_to_lng(x + 1, n);
    var north = y_tile_to_lat(y, n);

    return {
        west_longitude: x_tile_to_lng(x, n),
        south_latitude: y_tile_to_lat(y + 1, n),
        east_longitude: x_tile_to_lng(x + 1, n),
        north_latitude: y_tile_to_lat(y, n)
    };
}

Quadkey

A quadkey is a string of numbers (0-3) which captures the hierarchy of parent-child tiles from level 1 to the target tile level. The partitioning is the same as the Tile address described in the previous section.

As such, a quadkey can be converted to the bounding box that it represents in order to request information for that area.

  • Traffic API v6: quadkey={quadkey}
  • Traffic API v7: in=bbox:{west longitude},{south latitude},{east longitude},{north latitude}

The quadkey must be converted to a bounding box. For more information, see Convert quadkey to bounding box.

  • Traffic API v6 example: quadkey=120210233222
  • Traffic API v7 example: in=bbox:13.359375,52.482780,13.447266,52.536273

Convert quadkey to bounding box

In order to build a request for a quadkey, the quadkey must first be converted to a tile address. Then the algorithm provided in Convert tile address to bounding box can be used to convert the newly converted tile address into a bounding box to be sent as a request parameter.

The conversion algorithm to convert a quadkey to a tile address is found in the following code sample:

JavaScript
/** Convert a quadkey to its tile address
 *
 * @param {string} A string containing a quadkey
 *
 * @returns {Object} Tile address stored in an object with keys `zoom`, `x`,
 * and `y`
 */
function quadkey_to_tile(quadkey) {
    var x = 0;
    var y = 0;
    var zoom = quadkey.length;

    for (var idx = 0; idx < quadkey.length; idx++) {
        var quad = parseInt(quadkey.charAt(idx));
        var mask = 1 << (zoom - idx - 1);
        if (quad & 0x1) {
            x |= mask;
        }
        if (quad & 0x2) {
            y |= mask;
        }
    }

    return {
        zoom: zoom,
        x: x,
        y: y
    };
}

Finally, both algorithms can be used together to convert directly from a quadkey to a bounding box that gives the geographical extent of the tile that the quadkey represents, as seen in the following code sample:

JavaScript
/** Convert a quadkey to the bounding box for that tile
 *
 * @param {string} A string containing a quadkey
 *
 * @returns {Object} Bounding box is an object with keys for each of the 4
 * bounds west longitude, south latitude, east longitude, and north latitude
 */
function quadkey_to_bbox(quadkey) {
    var tile = quadkey_to_tile(quadkey);
    var bbox = tile_to_bbox(tile.zoom, tile.x, tile.y);

    return bbox;
}

results matching ""

    No results matching ""