carmen

Mapnik vector tile-based geocoder with support for swappable data sources. This is an implementation of some of the concepts of Error-Correcting Geocoding by Dennis Luxen.

Depends

• Node v18.x.x

Running on ARM64 (M1 Macs)

The various packages used by Carmen are not compiled for arm64, only x86-64, so npm install will not work as-is on M1 Macs. The easiest way to do this is install dependencies and run Carmen within a Rosetta-enabled iTerm window. When Rosetta is enabled, the architeture will present as x86_64, so nvm install will install the node version compiled for x64 instead of darwin.

To setup iTerm for Rosetta mode, open Finder -> Applications -> right-click on Iterm -> click Get Info -> check "Open using Rosetta".

With an iTerm window running in Rosetta mode, execute the following nvm install 18 command to install node compiled for x64:

➜  ~ nvm install 18
Downloading and installing node v18.19.0...
Local cache found: ${NVM_DIR}/.cache/bin/node-v18.19.0-darwin-x64/node-v18.19.0-darwin-x64.tar.xz
Checksums match! Using existing downloaded archive ${NVM_DIR}/.cache/bin/node-v18.19.0-darwin-x64/node-v18.19.0-darwin-x64.tar.xz
Now using node v18.19.0 (npm v10.2.3)

If the output specifies -darwin-arm64 instead of -darwin-x64, then iTerm is not running with Rosetta mode enabled.

To verify that the x64-compiled version of node is installed, run node -e 'console.log(process.arch)', which should output 'x64`:

➜  ~ node -e 'console.log(process.arch)'
x64

Non-Rosetta Terminal Applications

If using a terminal window other than iTerm or Terminal (such as Kitty), you will need to run the arch command before install nodejs. The following commands will changes the architecture mode to x64, then reinstall node 18:

1. change architecture to x86_64: arch -x86_64 /bin/zsh
2. uninstall arm64-compiled node: nvm uninstall 18
3. install x64-compiled node: nvm install 18
4. verify x64 node: node -e 'console.log(process.arch)'

Install

npm install

Carmen no longer ships with any default or sample data. Sample data will be provided in a future release.

If this command outputs an error like (note the "arm64"):

Output:
node-pre-gyp info it worked if it ends with ok
node-pre-gyp info using [email protected]
node-pre-gyp info using [email protected] | darwin | arm64
node-pre-gyp WARN Using request for node-pre-gyp https download 
node-pre-gyp info check checked for "/Users/stephenhess/git/mapbox/api-geocoder/node_modules/@mapbox/carmen-core-private/native/index.node" (not found)
node-pre-gyp http GET https://mapbox-node-binary.s3.amazonaws.com/node-carmen-core/v0.5.25/Release/node-v108-darwin-arm64.tar.gz

then the terminal is not running in Rosetta/x64-compatible mode. To resolve, see the "Running on ARM64 (M1 Macs)" section above.

Publish

Carmen is consumed by api-geocoder as a a node_modules package dependency. While developing and testing, you can publish a development release of Carmen.

To do this, first update the version field of the package.json file, using the following convention:

"version": "34.3.<next patch version>.<branch/feature name>"

mbx npm publish --tag dev

Once the feature has been E2E tested through api-geocoder and is ready to be merged into production, update the package.json version to its offical semver number (34.3.<next patch version>) and publish a production release:

mbx npm publish

Finally, update the package inside api-geocoder.

API

For a simplified example of using the carmen API, see the example folder in this repository.

For more detail about specific elements of the API (and how to use them directly), see the API Docs.

Command-line scripts

Carmen comes with command line utilities that also act as examples of API usage.

To query the default indexes:

./bin/carmen-index.js --query="new york"

To analyze an index:

./bin/carmen-analyze.js tiles/01-ne.country.mbtiles

Documentation

Carmen documentation has three parts:

• General documentation
• An example project
• API documentation

General Documentation

Topic-based documentation is located in the docs directory, organized by topic. These documents are meant to cover high-level design or architectural concepts rather than the code itself. It also includes a glossary of frequently-used vocabulary.

Example Project

The example project is located in the example directory. It is a step-by-step, annotated tutorial for basic usage of carmen.

API Documentation

API documentation is written as JSDoc comments in the source code. It is also available as a markdown-formatted document: docs/api.md. This document is generated using documentationjs, and should be updated after any JSDoc comment changes:

yarn build-docs

API Documentation Style Guide

• Classes, methods, events, and anything else must be documented with JSDoc comments.
• Text within JSDoc comments may use markdown formatting. Code identifiers must be surrounded by `backticks`.
• Documentation must be written in grammatically correct sentences ending with periods.
• Documentation descriptions must contain more information than what is obvious from the identifier and JSDoc metadata.
• Class descriptions should describe what the class is, or what its instances are. They do not document the constructor, but the class. They should begin with either a complete sentence or a phrase that would complete a sentence beginning with "A T is..." or "The T class is..." Examples: "Lists are ordered indexed dense collections." "A class used for asynchronous computations."
• Function descriptions should begin with a third person singular present tense verb, as if completing a sentence beginning with "This function..." If the primary purpose of the function is to return a value, the description should begin with "Returns..." Examples: "Returns the layer with the specified id." "Sets the map's center point."
• @param, @property, and @returns descriptions should be capitalized and end with a period. They should begin as if completing a sentence beginning with "This is..." or "This..."
• Functions that do not return a value (return undefined), should not have a @returns annotation.
• Member descriptions should document what a member represents or gets and sets. They should also indicate whether the member is read-only.
• Event descriptions should begin with "Fired when..." and so should describe when the event fires. Event entries should clearly document any data passed to the handler, with a link to MDN documentation of native Event objects when applicable.