carmenMapnik 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.
Carmen no longer ships with any default or sample data. Sample data will be provided in a future release.
APIFor a simplified example of using the carmen API, see the
examplefolder in this repository.
For more detail about specific elements of the API (and how to use them directly), see the API Docs.
Command-line scriptsCarmen comes with command line utilities that also act as examples of API usage.
To query the default indexes:
To analyze an index:
./bin/carmen-index.js --query="new york"
DocumentationCarmen documentation has three parts:
General DocumentationTopic-based documentation is located in the
docsdirectory, 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 ProjectThe example project is located in the
exampledirectory. It is a step-by-step, annotated tutorial for basic usage of carmen.
API DocumentationAPI 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:
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
Tis..." or "The
Tclass 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."
@returnsdescriptions 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
- 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.