Skip to content

Latest commit

 

History

History
237 lines (204 loc) · 10.7 KB

API.md

File metadata and controls

237 lines (204 loc) · 10.7 KB
Raw

This file documents efforts toward establishing a public API for Rapid.

URL parameters

Rapid Standalone

Rapid supports several URL parameters. When constructing a URL to a standalone instance of Rapid (e.g. https://mapwith.ai/rapid), the following parameters are available in the hash portion of the URL:

  • background - The value of the id property of the source in Rapid's imagery list, or a custom tile URL. A custom URL is specified in the format custom:<url>, where the URL can contain the standard tile URL placeholders {x}, {y} and {z}/{zoom}, {ty} for flipped TMS-style Y coordinates, and {switch:a,b,c} for DNS multiplexing.
    Example: background=custom:https://{switch:a,b,c}.tile.openstreetmap.org/{zoom}/{x}/{y}.png
  • comment - Prefills the changeset comment. Pass a url encoded string.
    Example: comment=CAR%20crisis%2C%20refugee%20areas%20in%20Cameroon
  • datasets - A comma-separated list of dataset IDs to enable
    Example: datasets=fbRoads,msBuildings,e75b56f13b404d7d8b47ef8be1c619ec
  • disable_features - Disables features in the list.
    Example: disable_features=water,service_roads,points,paths,boundaries
    Available features: points, traffic_roads, service_roads, paths, buildings, building_parts, indoor, landuse, boundaries, water, rail, pistes, aerialways, power, past_future, others
  • gpx - A custom URL for loading a gpx track. Specifying a gpx parameter will automatically enable the gpx layer for display.
    Example: gpx=https://tasks.hotosm.org/project/592/task/16.gpx
  • hashtags - Prefills the changeset hashtags. Pass a url encoded list of event hashtags separated by commas, semicolons, or spaces. Leading '#' symbols are optional and will be added automatically. (Note that hashtag-like strings are automatically detected in the comment).
    Example: hashtags=%23hotosm-task-592,%23MissingMaps
  • id - The character 'n', 'w', or 'r', followed by the OSM ID of a node, way or relation, respectively. Selects the specified entity, and, unless a map parameter is also provided, centers the map on it.
    Example: id=n1207480649
  • locale - A code specifying the localization to use, affecting the language, layout, and keyboard shortcuts. Multiple codes may be specified in order of preference. The first valid code will be the locale, while the rest will be used as fallbacks if certain text hasn't been translated. The default locale preferences are set by the browser.
    Example: locale=ja, locale=pt-BR, locale=nl,fr,de
    Available values: Any of the supported locales.
  • map - A slash-separated zoom/latitude/longitude.
    Example: map=20.00/38.90085/-77.02271
  • offset - Background imagery alignment offset in meters, formatted as east,north.
    Example: offset=-10,5
  • photo_overlay - The street-level photo overlay layers to enable.
    Example: photo_overlay=streetside,mapillary,kartaview
    Available values: streetside (Microsoft Bing), mapillary, mapillary-signs, mapillary-map-features, kartaview
  • photo_dates - The range of capture dates by which to filter street-level photos. Dates are given in YYYY-MM-DD format and separated by _. One-sided ranges are supported.
    Example: photo_dates=2019-01-01_2020-12-31, photo_dates=2019-01-01_, photo_dates=_2020-12-31
  • photo_username - The Mapillary or KartaView username by which to filter street-level photos. Multiple comma-separated usernames are supported.
    Example: photo_user=quincylvania, photo_user=quincylvania,chrisbeddow
  • photo - The service and ID of the street-level photo to show.
    Example: photo=streetside/718514589
    Available prefixes: streetside/, mapillary/, kartaview/
  • presets - A comma-separated list of preset IDs. These will be the only presets the user may select.
    Example: presets=building,highway/residential,highway/unclassified
  • rtl=true - Force Rapid into right-to-left mode (useful for testing).
  • source - Prefills the changeset source. Pass a url encoded string.
    Example: source=Bing%3BMapillary
  • validationDisable - The issues identified by these types/subtypes will be disabled (i.e. Issues will not be shown at all). Each parameter value should contain a urlencoded, comma-separated list of type/subtype match rules. An asterisk * may be used as a wildcard.
    Example: validationDisable=crossing_ways/highway*,crossing_ways/tunnel*
  • validationWarning - The issues identified by these types/subtypes will be treated as warnings (i.e. Issues will be surfaced to the user but not block changeset upload). Each parameter value should contain a urlencoded, comma-separated list of type/subtype match rules. An asterisk * may be used as a wildcard.
    Example: validationWarning=crossing_ways/highway*,crossing_ways/tunnel*
  • validationError - The issues identified by these types/subtypes will be treated as errors (i.e. Issues will be surfaced to the user but will block changeset upload). Each parameter value should contain a urlencoded, comma-separated list of type/subtype match rules. An asterisk * may be used as a wildcard.
    Example: validationError=crossing_ways/highway*,crossing_ways/tunnel*
  • walkthrough=true - Start the walkthrough automatically

Customized Deployments

Rapid may be used to edit maps in a non-OpenStreetMap environment. This requires certain parts of the Rapid code to be replaced at runtime by custom code or data.

Rapid is written in a modular style and bundled with rollup.js, which makes hot code replacement tricky. (ES6 module exports are immutable live bindings). Because of this, the parts of Rapid which are designed for customization are exported as live bound objects that can be overridden at runtime before initializing the Rapid context.

Background Imagery

Rapid's background imagery database is stored in the Rapid.fileFetcher.cache().imagery array and can be overridden or modified prior to creating the Rapid context.

Note that the "None" and "Custom" options will always be shown in the list.

To remove all imagery from Rapid:

Rapid.fileFetcher.cache().imagery = [];

To replace all imagery with a single source:

Rapid.fileFetcher.cache().imagery = [{
    "id": "ExampleImagery",
    "name": "My Imagery",
    "type": "tms",
    "template": "http://{switch:a,b,c}.tiles.example.com/{z}/{x}/{y}.png"
}];

Each imagery source should have the following properties:

  • id - Unique identifier for this source (also used as a url parameter)
  • name - Display name for the source
  • type - Source type, currently only tms is supported
  • template - Url template, valid replacement tokens include:
    • {z}, {x}, {y} - for Z/X/Y scheme
    • {-y} or {ty} - for flipped Y
    • {u} - for quadtile scheme
    • {switch:a,b,c} - for parts of the url that can be cycled for connection parallelization

Optional properties:

  • description - A longer source description which, if included, will be displayed in a popup when viewing the background imagery list
  • overlay - If true, this is an overlay layer (a transparent layer rendered above base imagery layer). Defaults to false
  • zoomExtent - Allowable min and max zoom levels, defaults to [0, 22]
  • polygon - Array of coordinate rings within which imagery is valid. If omitted, imagery is assumed to be valid worldwide
  • terms_url - Url to link to when displaying the imagery terms
  • terms_html - Html content to display in the imagery terms
  • terms_text - Text content to display in the imagery terms
  • best - If set to true, this imagery is considered "better than Bing" and may be chosen by default when Rapid starts. Will display with a star in the background imagery list. Defaults to false

For more details about the Rapid.fileFetcher.cache().imagery structure, see update_imagery.js.

Presets

Rapid supports presets that conform to the iD tagging schema.

Rapid's preset database is stored in the Rapid.fileFetcher.cache().presets object and can be overridden or modified prior to creating the Rapid context.

To add a new preset to Rapid's existing preset database.

Rapid.fileFetcher.cache().presets.presets["aerialway/zipline"] = {
    geometry: ["line"],
    fields: ["incline"],
    tags: { "aerialway": "zip_line" },
    name: "Zipline"
};

To completely replace Rapid's default presets with your own:

Rapid.fileFetcher.cache().presets = myPresets;

To run Rapid with the minimal set of presets that only match basic geometry types:

Rapid.fileFetcher.cache().presets = {
    presets: {
        "area": {
            "name": "Area",
            "tags": {},
            "geometry": ["area"]
        },
        "line": {
            "name": "Line",
            "tags": {},
            "geometry": ["line"]
        },
        "point": {
            "name": "Point",
            "tags": {},
            "geometry": ["point"]
        },
        "vertex": {
            "name": "Vertex",
            "tags": {},
            "geometry": ["vertex"]
        },
        "relation": {
            "name": "Relation",
            "tags": {},
            "geometry": ["relation"]
        }
    }
};

Custom Presets

Rapid supports deployments which use a custom set of presets. You can supply presets via the presets accessor:

var id = Rapid.coreContext().presets({
    presets: { ... },
    fields: { ... },
    defaults: { ... },
    categories: { ... }
});

All four parts (presets, fields, defaults, and categories) must be supplied. In addition, several base presets and fields must be included.

Basic geometric presets must be included so that every feature matches at least one preset. For example:

"area": {
    "name": "Area",
    "tags": {},
    "geometry": ["area"],
    "matchScore": 0.1
},
"line": {
    "name": "Line",
    "tags": {},
    "geometry": ["line"],
    "matchScore": 0.1
},
"point": {
    "name": "Point",
    "tags": {},
    "geometry": ["point", "vertex"],
    "matchScore": 0.1
},
"relation": {
    "name": "Relation",
    "tags": {},
    "geometry": ["relation"],
    "matchScore": 0.1
}

A "name" field must be included:

"name": {
    "key": "name",
    "type": "localized",
    "label": "Name",
    "placeholder": "Common name (if any)"
}