# Straßenvorschläge beim Tippen (https://developer.bimetrics.de/reference/contacts/suggest-streets)

`GET https://app.bimetrics.de/api/address/streets`

operationId: `suggestStreets` · Berechtigung (Scope): `contacts:read` · Bereich: Kontakte

Schlägt für Deutschland bis zu 8 Straßen vor, deren Name so beginnt wie `q`, mit Ort und Postleitzahlen. Das sind dieselben Daten wie die Vorschläge im Feld „Straße und Hausnummer“ des Kontaktformulars der App. Gesucht wird erst ab drei Buchstaben, darunter bleibt `streets` leer. Schreibweise wie beim Ort: Groß- und Kleinschreibung und Satzzeichen zählen nicht, „ue“ gilt als „ü“, „Str.“ und „Straße“ gelten gleich. Eine Hausnummer am Ende stört nicht. Mit `city` grenzt du ein: Meint der Name genau einen Ort, kommen nur dessen Straßen, sonst die aller Orte, die so beginnen („Frankfurt“ trifft Frankfurt am Main und Frankfurt (Oder)). Mit `postalCode` kommen nur Straßen, die diese Postleitzahl haben. Reihenfolge: ein genau getippter Name vor längeren, dann Straßen in größeren Orten zuerst. Ohne `city` sortiert `near` (eine Postleitzahl, in der App die der eigenen Firma) die Straßen aus der Nähe nach vorn: zuerst nach gleichen führenden Ziffern, dann nach dem Abstand der Leitregionen, erst dann nach der Ortsgröße. Die Liste ist nicht vollständig, OpenStreetMap kennt nicht jede Straße, und Hausnummern fehlen ganz. Eine Straße ohne Vorschlag ist deshalb kein Fehler. Für andere Länder kommt `supported: false`. Ohne `q` antwortet die Route mit `400` und `context.field` = `q`. Quelle: OpenStreetMap (ODbL 1.0). Zeigst du die Vorschläge an, nenne `attribution` mit Link auf https://www.openstreetmap.org/copyright.

Benötigt einen Schlüssel mit der Berechtigung `contacts:read` oder `read`.

### Authentifizierung

`Authorization: Bearer bm_…` (alternativ `X-API-KEY: bm_…`, nie beide zugleich).

### Parameter

| Name | Ort | Pflicht | Typ | Beschreibung |
| --- | --- | --- | --- | --- |
| `country` | query | nein | string | Land als ISO-Code. Nur `DE` liefert Vorschläge; ein Name wie „Deutschland“ geht auch. |
| `q` | query | ja | string | Der getippte Anfang der Straße, gern mit Hausnummer. |
| `city` | query | nein | string | Ortsname, ganz oder als Anfang, geschrieben wie bei `GET /api/address/postal`. |
| `postalCode` | query | nein | string | Postleitzahl; Leerzeichen zählen nicht. |
| `near` | query | nein | string | Postleitzahl, deren Nähe ohne `city` die Reihenfolge bestimmt, fünf Ziffern; mit `city` ohne Wirkung. Eine andere Form ergibt `400` mit `context.field` = `near`. |

### Beispiel

```sh
curl --fail-with-body "https://app.bimetrics.de/api/address/streets" \
  -H "Authorization: Bearer $BIMETRICS_API_KEY"
```

### Antworten

| Status | Beschreibung | Inhalt |
| --- | --- | --- |
| 200 | Erfolg. | `application/json`: StreetLookup |
| 400 | Ungültige Anfrage, z. B. ein Parameter mit ungültigem Wert wie eine ID, die keine UUID ist; korrigieren statt wiederholen. Mehr unter [Fehler](https://developer.bimetrics.de/errors). | `application/json`: Error |
| 401 | Kein gültiger Schlüssel: fehlt (`Unauthorized`), ist unbekannt, abgelaufen oder widerrufen oder wurde nicht in genau einem Header gesendet (`InvalidAPIKey`). Schlüssel prüfen, nicht wiederholen. Auch eine ID, die zu einer anderen Firma gehört, ergibt `401 Unauthorized`. | `application/json`: Error |
| 403 | Dem Schlüssel fehlt die Berechtigung für diese Route (`APIKeyPermissionDenied`), oder die Firma hat keinen API-Zugang (mehr), etwa nach Ende der Testphase oder des Abos (`APIUnavailable`). | `application/json`: Error |
| 413 | Die Anfrage ist zu groß (`APIRequestTooLarge`), siehe `x-bimetrics-limits`. | `application/json`: Error |
| 429 | Zu viele Anfragen; nach `Retry-After` Sekunden erneut senden. Mehr unter [Fehler](https://developer.bimetrics.de/errors). (Header: Retry-After) | `application/json`: Error |
| 500 | Serverfehler; die Anfrage später wiederholen. Mehr unter [Fehler](https://developer.bimetrics.de/errors). | `application/json`: Error |

#### Felder der Antwort 200 (`StreetLookup`)

| Feld | Typ | Beschreibung |
| --- | --- | --- |
| `attribution` | string | Namensnennung, die zu den Vorschlägen gehört: „© OpenStreetMap-Mitwirkende“. |
| `country` | string | Land der Anfrage als ISO-Code. |
| `source` | string | Quelle der Liste: `osm` (OpenStreetMap); fehlt bei anderen Ländern. |
| `streets` | Array<StreetSuggestion>, kann null sein | Bis zu 8 Straßen, der genaue Name zuerst, dann Straßen in größeren Orten; leer unter drei Buchstaben, ohne Treffer oder für andere Länder. |
| `supported` | boolean | `true` für DE, sonst `false` mit leerer Liste. |

Verschachtelte Schemas stehen vollständig in der OpenAPI-Beschreibung: https://app.bimetrics.de/api/openapi.json
