Addresses

Address help: whole addresses suggested as people type, from Google's Places API through the ERP (only the text typed and the country reach Google), the parts of the one chosen, and the towns of a postal code from open data shipped with Stabiso. Nothing is stored.

Operation	Summary	Scope
`GET /v1/addresses/details`	Get the parts of a suggested address	`read`
`GET /v1/addresses/suggestions`	Suggest addresses	`read`
`GET /v1/addresses/towns`	Find the town of a postal code	`read`

`GET /v1/addresses/details`

Get the parts of a suggested address

The street, building number, postal code, town, canton or state and country of the address chosen, to fill a form with. 404 address_not_found when the server suggests no addresses or Google does not know or give it. An organization may ask for 2,000 a day.


Required scope	`read` (`admin` implies every scope)
Operation id	`address_details_v1_addresses_details_get`

Parameters

In	Name	Type	Required	Description
query	`session`	string	yes	A token the caller makes once per address typed (a UUID) and sends with every suggestion and the details of the one chosen: Google charges the address chosen, not the suggestions before it. (pattern `^[A-Za-z0-9_-]{8,64}$`)
query	`suggestion`	string	yes	The `id` of a suggestion of `GET /v1/addresses/suggestions`. (pattern `^[A-Za-z0-9_-]{1,300}$`)
query	`language`	string		The language of the names (`de`). (pattern `^[a-z]{2}(-[A-Za-z]{2})?$`; default `"en"`)

Example request

curl "$ERP_URL/v1/addresses/details?session=value&suggestion=value" \
  -H "Authorization: Bearer $ERP_KEY"

Responses

Status	Meaning	Body
200	OK	`AddressOut`
401	Missing or invalid API key (`unauthorized`).	`ErrorEnvelope`
403	The caller lacks the required scope (`missing_right`, with `scope`), the key belongs to no person where a person is needed (`forbidden`), or the approval policy denies the action (`policy_denied`, with `action` and `rule_id`).	`ErrorEnvelope`
422	Validation failed: the error envelope (`validation_failed`). For a malformed body or parameter its message is in sentences ("Line 2: the quantity must be above zero") and `fields` lists each error with pydantic's `loc`, `type` and `msg` beside its sentence (`message`) and its parts, to word it in another language: `items` (`name` and `number` from 1: line 2), `field` (its name as sent) and the `rule` it breaks with its `limit`, `count` and `choices` (none for a validator's own sentence); FastAPI's own `detail` list stays beside the envelope.	`HTTPValidationError`

Example response (shape)

{
  "street": "string",
  "building_number": "string",
  "postal_code": "string",
  "town": "string",
  "subdivision": "string",
  "country": "string",
  "text": "string"
}

`GET /v1/addresses/suggestions`

Suggest addresses

At most five whole addresses that match what was typed (streets with or without a number, no shops or sights), best first, from Google's Places API. available is false on a server without its key; the list is then empty, as it is when Google does not answer. An organization may ask for 5,000 a day (429 rate_limited after).


Required scope	`read` (`admin` implies every scope)
Operation id	`suggest_addresses_v1_addresses_suggestions_get`

Parameters

In	Name	Type	Required	Description
query	`session`	string	yes	A token the caller makes once per address typed (a UUID) and sends with every suggestion and the details of the one chosen: Google charges the address chosen, not the suggestions before it. (pattern `^[A-Za-z0-9_-]{8,64}$`)
query	`text`	string		What was typed so far; under three characters nothing is asked of Google (empty: only whether addresses are suggested here). (max length 120; default `""`)
query	`country`	string		Only addresses in this country (ISO 3166-1 alpha-2); empty: anywhere. (pattern `^([A-Za-z]{2})?$`; default `""`)
query	`language`	string		The language of the names (`de`). (pattern `^[a-z]{2}(-[A-Za-z]{2})?$`; default `"en"`)

Example request

curl "$ERP_URL/v1/addresses/suggestions?session=value" \
  -H "Authorization: Bearer $ERP_KEY"

Responses

Status	Meaning	Body
200	OK	`AddressSuggestionsOut`
401	Missing or invalid API key (`unauthorized`).	`ErrorEnvelope`
403	The caller lacks the required scope (`missing_right`, with `scope`), the key belongs to no person where a person is needed (`forbidden`), or the approval policy denies the action (`policy_denied`, with `action` and `rule_id`).	`ErrorEnvelope`
422	Validation failed: the error envelope (`validation_failed`). For a malformed body or parameter its message is in sentences ("Line 2: the quantity must be above zero") and `fields` lists each error with pydantic's `loc`, `type` and `msg` beside its sentence (`message`) and its parts, to word it in another language: `items` (`name` and `number` from 1: line 2), `field` (its name as sent) and the `rule` it breaks with its `limit`, `count` and `choices` (none for a validator's own sentence); FastAPI's own `detail` list stays beside the envelope.	`HTTPValidationError`

Example response (shape)

{
  "available": true,
  "suggestions": [
    {
      "id": "string",
      "text": "string",
      "main": "string",
      "secondary": "string"
    }
  ]
}

`GET /v1/addresses/towns`

Find the town of a postal code

The towns a postal code covers, each with its canton or state, from open postal code data shipped with Stabiso (no call to anyone): AT, BE, CH, DE, DK, ES, IT, LI, LU, NL, NO, SE and US (the state only). Empty for an unknown code or another country.


Required scope	`read` (`admin` implies every scope)
Operation id	`postal_code_towns_v1_addresses_towns_get`

Parameters

In	Name	Type	Required	Description
query	`country`	string	yes	The country, ISO 3166-1 alpha-2 (`CH`). (pattern `^[A-Za-z]{2}$`)
query	`postal_code`	string	yes	The postal code (`8001`). (min length 1; max length 16)

Example request

curl "$ERP_URL/v1/addresses/towns?country=value&postal_code=value" \
  -H "Authorization: Bearer $ERP_KEY"

Responses

Status	Meaning	Body
200	OK	`PostalTownsOut`
401	Missing or invalid API key (`unauthorized`).	`ErrorEnvelope`
403	The caller lacks the required scope (`missing_right`, with `scope`), the key belongs to no person where a person is needed (`forbidden`), or the approval policy denies the action (`policy_denied`, with `action` and `rule_id`).	`ErrorEnvelope`
422	Validation failed: the error envelope (`validation_failed`). For a malformed body or parameter its message is in sentences ("Line 2: the quantity must be above zero") and `fields` lists each error with pydantic's `loc`, `type` and `msg` beside its sentence (`message`) and its parts, to word it in another language: `items` (`name` and `number` from 1: line 2), `field` (its name as sent) and the `rule` it breaks with its `limit`, `count` and `choices` (none for a validator's own sentence); FastAPI's own `detail` list stays beside the envelope.	`HTTPValidationError`

Example response (shape)

{
  "country": "string",
  "postal_code": "string",
  "towns": [
    {
      "town": "string",
      "subdivision": "string"
    }
  ]
}

Schemas

`AddressOut`

Field	Type	Required	Description
`street`	string or null	yes	The street, without the number.
`building_number`	string or null	yes	The building number.
`postal_code`	string or null	yes	The postal code.
`town`	string or null	yes	The town (the locality, or the postal town).
`subdivision`	string or null	yes	The canton or state as an ISO 3166-2 code (`CH-ZH`, `US-CA`) where the address forms pick it from a list (CH, DE, AT, US, CA); else null.
`country`	string or null	yes	The country, ISO 3166-1 alpha-2.
`text`	string	yes	The whole address as Google writes it.

`AddressSuggestion`

Field	Type	Required	Description
`id`	string	yes	What `GET /v1/addresses/details` takes to fill the address.
`text`	string	yes	The whole address as it is suggested.
`main`	string	yes	Its first part: the street and number, or the place.
`secondary`	string	yes	The rest: postal code, town, country.

`AddressSuggestionsOut`

Field	Type	Required	Description
`available`	boolean	yes	Whether addresses are suggested on this server: false while it has no key for Google's Places API (then `suggestions` is always empty, and the postal code still gives the town).
`suggestions`	array of `AddressSuggestion`	yes	At most five addresses that match the text, best first.

`PostalTown`

Field	Type	Required	Description
`town`	string or null	yes	The town of the postal code; null where only its state is known (US).
`subdivision`	string or null	yes	The canton or state as an ISO 3166-2 code (`CH-ZH`, `US-CA`) where the address forms pick it from a list (CH, DE, AT, US); else null.

`PostalTownsOut`

Field	Type	Required	Description
`country`	string	yes	The country asked, ISO 3166-1 alpha-2.
`postal_code`	string	yes	The postal code asked, as given.
`towns`	array of `PostalTown`	yes	The towns the postal code covers, by name (one for most; several where a code serves several villages); empty for an unknown code or a country without a list.