Country and address type

Coverage and restricting results to countries

The service is international. The address sources behind it cover many countries, and the countries enabled for a deployment are configuration, extended on request. DE and AT are the examples on these pages and the current default, not the limit. Pending verification: the list of countries enabled on sandbox and production, and how complete the results are per country.

To restrict results to one or more countries, send countries with the codes you want, on every predict call. Germany is the example:

{ "input": "Hauptstr 12", "countries": ["DE"] }

Only German suggestions come back. Several countries work the same way, for example ["DE", "FR"] where both are enabled. The widget takes the same list as an option, countries: ['DE'].

How it relates to the service-wide settings

The service has two country settings. Both are service-wide, not per key or per account:

What that means for a request:

• countries narrows the default. ["DE"] gives Germany only even when the default is Germany and Austria.
• countries is checked against the enabled list, not the default. If the service default were narrowed to one country, a request can still name another enabled country. The default is what you get when you say nothing; it is not a ceiling.
• Omitting countries, sending null or sending an empty list [] means the default. An empty list does not mean "no country". With the default at DE and AT, a call without countries returns Austrian suggestions too.
• Codes are case-insensitive (de works). Do not send blank strings.
• A country that is not enabled returns 422 with a string detail, for example Country not enabled: CH. Allowed: DE, AT (the list shown is whatever is enabled for the deployment).
• resolve takes no countries. The suggestion id already belongs to a country.

So a client that must only ever accept German addresses has to send countries: ["DE"] itself, because the default can include other countries (today Austria). Do not rely on the service default for this.

Also check the result on your side. After resolve, test address.country_code === "DE" before you accept the address; that guards against a missing countries value and against a changed service default.

Pending verification: the per-request restriction is passed to the address source, and its behaviour on the live service (for example a German-looking street name that exists only in Austria) has not been tested. The gateway may also set its own defaults; that is pending verification.

Residential, commercial and mixed addresses

Not supported today. The service has no filter for residential, commercial or mixed-use addresses, and the response does not say which kind an address is.

What you can rely on:

• Request. predict accepts input, session, countries, language and near. None of them filters by address type, and there is no field for it.
• Response. A resolved address carries formatted, street, house_number, postal_code, city, district, state, country, country_code, lat, lng and precision. None of them describes how the address is used.
• precision is not an address type. It says how far the address was resolved: house (down to a house number), street or area. A house result can be a home, a shop or an office.
• verification is not an address type either. It reports whether a second source agrees on postcode, city, house number and position.

Do not try to infer the type from the text or the coordinates. The result would look like data and would be a guess.

Why this is hard in general

This is a property of address data, not only of this service:

• A single source classifies only some addresses. Where a source carries a use label at all, it covers part of the addresses, and many records have none.
• Combining sources improves coverage. When two sources are consulted, an address that one cannot classify may be labelled by the other. The labels still need reconciling when the sources disagree, and a second lookup adds time to a type-ahead.
• Buildings are often mixed. A label usually describes a building or an entrance, not a person's flat. A building with some residential and some commercial units is mixed, and a filter has to decide what to do with it: hide it, or show it and let the user decide.
• A label is not proof of residence. A residential address says nothing about whether this person lives there. If you need to check that, see Address verification, which is a separate service.

If your product needs an address-type filter, tell us which behaviour you want for mixed buildings and for addresses with no label (hide, show, or flag). That decides how it would be built. There is no date for it.