Nattily Polished Marbles


    0.14.1-beta.3 • Public • Published

    Build status

    OSRM Text Instructions

    OSRM Text Instructions is a Node.js library that transforms route data generated by OSRM into localized turn instructions to be displayed visually or read aloud by a text-to-speech engine. OSRM Text Instructions is the basis of guidance instructions in osrm-frontend, the Mapbox Directions API, and the Mapbox Navigation SDK.

    • Global: Text instructions are available in over a dozen languages via Transifex. Abbreviations and advanced grammatical transformations are available in some languages.
    • Customizable: Flexible options allow you to format and tweak the results to your liking.
    • Cross-platform: A data-driven approach facilitates implementations in other programming languages. OSRM Text Instructions is also available in Swift and Objective-C (for iOS, macOS, tvOS, and watchOS) and in Java (for Android and Java SE).
    • Well-tested: A data-driven test suite ensures compatibility across languages and platforms.



    var version = 'v5';
    var osrmTextInstructions = require('osrm-text-instructions')(version);
    response.legs.forEach(function(leg) {
      leg.steps.forEach(function(step) {
        instruction = osrmTextInstructions.compile('en', step, options)

    If you are unsure if the user's locale is supported by osrm-text-inustrctions, use @mapbox/locale-utils for finding the best fitting language.

    Parameters require('osrm-text-instructions')(version)

    parameter required? values description
    version required v5 Major OSRM version

    Parameters compile(language, step, options)

    parameter required? values description
    language required en de zh-Hans fr nl ru and more Compiling instructions for the selected language code.
    step required OSRM route step object The RouteStep as it comes out of OSRM
    options optional Object See below
    key type description
    legCount integer Number of legs in the route
    legIndex integer Zero-based index of the leg containing the step; together with legCount, this option determines which waypoint the user has arrived at
    formatToken function Function that formats the given token value after grammaticalization and capitalization but before the value is inserted into the instruction string; useful for wrapping tokens in markup
    waypointName string Optional custom name for the leg's destination, replaces "your {nth} destination"

    formatToken takes two parameters:

    • token: A string that indicates the kind of token, such as way_name or direction
    • value: A grammatical string for this token, capitalized if the token appears at the beginning of the instruction

    and returns a string.


    • index.js contains the main transformation logic in JavaScript.
    • languages/ contains the localization files, including raw format strings, abbreviation files, and grammar rules.
    • languages.js loads the localizations and contains some localization-related helper functions.
    • test/ contains data-driven integration tests and test fixtures for all supported languages.


    We welcome feedback, code contributions, and translations! Please see for details.





    npm i osrm-text-instructions

    DownloadsWeekly Downloads






    Unpacked Size

    6.37 MB

    Total Files


    Last publish


    • 1ec5
    • allierowan
    • bsudekum
    • danieljh
    • danpaz-mb
    • freenerd
    • lyzidiamond
    • mapbox-admin
    • mcwhittemore
    • mokob
    • themarex