Usage cookbook

Use-case-driven recipes for the fit-connect CLI. For the command reference see the README; for every term see the GLOSSARY.

All examples use --compact so output is one line per result, easy to pipe into jq. Drop it for pretty-printed JSON.

The two inputs. A routing lookup needs a Leistungsschlüssel (leikaKey, a 14-digit 99… key identifying the service) and one area selector (--ars / --ags / --area-id, identifying where). This CLI does not discover service keys — get them from the FIM-Portal / Leistungskatalog.

Find who is responsible for a service in a town

The headline use case, in two steps when you only know the place by name:

# 1) place name -> area id
fit-connect --compact areas "Hanau"
#   -> pick { "id": "940", "name": "Hanau, Brüder-Grimm-Stadt", "type": "kreisfreie Stadt" }

# 2) route the service into that area
fit-connect --compact routes 99123456760610 --area-id 940

If you already hold the official codes, do it in one call:

fit-connect --compact routes 99123456760610 --ars 160510000000
fit-connect --compact routes 99123456760610 --ags 16051000

Pull just the authority name and contact

fit-connect --compact routes 99123456760610 --ars 160510000000 \
  | jq -r '.routes[]
      | "\(.destinationName)\n  ☎ \(.contactPersons[0].tel // "-")  ✉ \(.contactPersons[0].email // "-")"'

Get the postal address of the responsible authority

fit-connect --compact routes 99123456760610 --area-id 940 \
  | jq -r '.routes[0].postalAddress
      | "\(.street) \(.houseNumber), \(.zip) \(.city)"'

Search areas

# By name (returns the place and its Ortsteile)
fit-connect --compact areas "Halle"

# By postal code
fit-connect --compact areas 60311

# Wildcard prefix match
fit-connect --compact areas "Mag*"

# Multiple terms are ANDed — every term must match the same area (narrows it)
fit-connect --compact areas Frankfurt am Main

# Just the top-level (non-Gemeindeteil) candidates
fit-connect --compact areas "Hanau" \
  | jq -r '.areas[] | select(.type != "Gemeindeteil") | "\(.id)\t\(.type)\t\(.name)"'

Page through a large area result

fit-connect --compact areas "Berlin" --limit 25 --offset 0
fit-connect --compact areas "Berlin" --limit 25 --offset 25

Count registered destinations for a service in an area

fit-connect --compact routes 99123456760610 --ars 160510000000 | jq '.totalCount'

A totalCount / count of 0 is a valid answer — no destination is registered for that service in that area. The command still exits 0.

Use the legacy v1 routing service

v2 is the default and current version. v1 takes the same inputs but its route results omit the encryption-key parameters; query it explicitly when you need it:

fit-connect --api-version v1 --compact routes 99123456760610 --area-id 940
fit-connect --api-version v1 info

Check the deployed API version

fit-connect --compact info
# {"version":{"major":2,"minor":0,"patch":0}}

Scripting patterns

# Resolve a place name to a single area id in one pipeline
AREA_ID=$(fit-connect --compact areas "Hanau" \
  | jq -r '.areas[] | select(.type=="kreisfreie Stadt") | .id' | head -n1)
fit-connect --compact routes 99123456760610 --area-id "$AREA_ID"

# Loop a service over several areas (ids from `fit-connect areas`)
for AREA in 940 1099 1024; do
  echo "== area $AREA =="
  fit-connect --compact routes 99123456760610 --area-id "$AREA" | jq -r '.routes[].destinationName'
done

# Raise the timeout on a slow connection
fit-connect --timeout 60000 --compact routes 99123456760610 --area-id 940

Exit codes in scripts

if fit-connect --compact routes 99123456760610 --ars 160510000000 >/tmp/r.json; then
  test "$(jq '.count' /tmp/r.json)" -gt 0 && echo "responsible authority found"
else
  echo "lookup failed (exit $?)" >&2   # 1 = error, 4 = 404
fi

Code	Meaning
`0`	Success — including an empty `routes: []` / `areas: []`
`4`	Not found (`404`)
`1`	Other API / network / parse / validation / usage error