Taginfo/Projects

Taginfo Projects
Projects list for Taginfo
Website:	Projects, Sources, Fetch status
Source repository:	taginfo/taginfo-projects GitHub

There are many projects using OSM tags in some way: editors, routers, maps, data extraction tools, ... Taginfo can get information from those projects about their use of OSM tags through 'project files'. The taginfo database keeps the information which projects use which keys and tags (optionally with descriptions and/or links to the documentation of the project). This information is then shown by taginfo on each of the key/tag pages in the 'Projects' tab (Examples: list of projects, Projects using key 'highway').

Project Files

Project files are descriptions provided by projects about their use of OSM tags. Project files use the JSON file format. They contains some meta data about the project itself and then a list of all keys and values used by the project and descriptions how they are used.

Here is how such a JSON file looks:

   {
       "data_format": 1,           # data format version, currently always 1, will get updated if there are incompatible changes to the format (required)
       "data_url": "...",          # this should be the URL under which this project file can be accessed (optional)
       "data_updated": "yyyymmddThhmmssZ", # timestamp when project file was updated (optional, will use HTTP header date if not available)
       "project": {                # meta information about the project (required)
           "name": "...",          # name of the project (required)
           "description": "...",   # short description of the project (required)
           "project_url": "...",   # home page of the project with general information (required)
           "doc_url": "...",       # documentation of the project and especially the tags used (optional)
           "icon_url": "...",      # project logo, should work in 16x16 pixels on white and light gray backgrounds (optional)
           "contact_name": "...",  # contact name, needed for taginfo maintainer (required)
           "contact_email": "..."  # contact email, needed for taginfo maintainer (required)
       },
       "tags": [...]               # list of keys and tags used (see below)
   }

Each of the "tags" looks like this:

   {
       "key": "...",          # OSM tag key (required)
       "value": "...",        # OSM tag value (optional, if not supplied it means "all values")
       "object_types": [...], # OSM object types this key/tag can be used for (optional, see below)
       "description": "...",  # how the key/tag is used in this project (optional)
       "doc_url": "...",      # link to further documentation of the project about this specific key/tag (optional)
       "icon_url": "..."      # URL of an icon, should work in 16x16 pixels on white and light gray backgrounds (optional)
   }

Do not use wildcard characters or regular expressions in any of the fields, in particular "value": "*" means a literal asterisk character in the value, not any value. If you mean any value, just do not specify the value at all.

The 'object_types' is an array of one or more of the following words: "node", "way", "relation", and "area". If there is no 'object_types' array, all types are allowed. You can have several entries in the tags list with the same key/value combination with different object_types.

The 'description' should reflect how the key/tag is used in the context of the project, it should NOT be a general description of the key/tag.

All text fields are for plain text only, no HTML or markdown or so.

The 'icon_url' image will be resized to 16x16; a higher resolution image will often look better in a high pixel density display.

Projects can create one project file or multiple project files if there are "subprojects" like multiple styles for the same map or so. Each project has to decide for themselves, whether this makes sense or not in their case.

Integration into Taginfo

Projects have to create their project files (typically called taginfo.json) somewhere on the web. Most often it will be in their Git or other repository, but it can be anywhere on the web. The URL of the project file then has to be given to Taginfo. If you have a Github account, read https://github.com/taginfo/taginfo-projects/blob/master/CONTRIBUTING.md, add the URL to https://github.com/taginfo/taginfo-projects/blob/master/project_list.txt and send a pull request. If you don't have a github account, then email the URL to jochen@remote.org.

Taginfo will periodically (usually daily) poll the project file and add the information to its own database. Fetch success reporting is available.

No project is too small or too large or too uninteresting. We want absolutely everybody's project in the database. Please consider adding your project, too!