How to Restrict Address Search to a Country

A user searches for an address, but the application serves locations only within one country or a small group of countries. Without a restriction, common street, city, and place names can produce valid results from unsupported countries.

Add a country restriction to Forward Geocoding, Reverse Geocoding, or Address Autocomplete requests so only supported countries can appear. Geoapify uses ISO 3166-1 alpha-2 codes such as de, us, and fr.

Understand country-filter syntax

A country filter is a hard restriction: results outside the selected countries are excluded. This differs from a country bias, which only prioritizes matching countries and can still return results elsewhere.

Forward Geocoding and Address Autocomplete accept a country filter in this form:

filter=countrycode:de

countrycode accepts lowercase ISO 3166-1 alpha-2 country codes, separated by commas. For example:

The dedicated countrycodes parameter is also available across the Forward Geocoding, Reverse Geocoding, and Address Autocomplete APIs:

countrycodes=de,at

Multiple countries

Use a comma-separated list in an API request, or pass an array to the autocomplete library:

autocomplete.addFilterByCountry(["de", "at"]);

We recommend restricting a request to no more than two or three countries. A focused country set produces more effective search and ranking; for broader searches, omit the restriction instead of adding a long country list.

Restrict Forward Geocoding to a country

https://api.geoapify.com/v1/geocode/search?text=Alexanderplatz&filter=countrycode:de&format=json&apiKey=YOUR_API_KEY

This is a hard restriction: matching locations outside Germany are excluded.

Restrict Reverse Geocoding to a country

Reverse Geocoding uses countrycodes to restrict the lookup. This example requests an address for coordinates in Berlin and accepts results only from Germany:

https://api.geoapify.com/v1/geocode/reverse?lat=52.5200&lon=13.4050&countrycodes=de&format=json&apiKey=YOUR_API_KEY

If the coordinates do not resolve to an allowed country, the response contains no matching result. This can be useful when an application must reject map clicks or device locations outside its service area.

Restrict Address Autocomplete API to a country

https://api.geoapify.com/v1/geocode/autocomplete?text=Alex&filter=countrycode:de&format=json&apiKey=YOUR_API_KEY

The API returns suggestions only from Germany. When calling it directly from an input field, add a short debounce and cancel superseded requests so every keystroke does not create an unnecessary request.

Restrict @geoapify/geocoder-autocomplete to a country

The Geoapify autocomplete control provides addFilterByCountry():

import { GeocoderAutocomplete } from "@geoapify/geocoder-autocomplete";
import "@geoapify/geocoder-autocomplete/styles/minimal.css";

const autocomplete = new GeocoderAutocomplete(
  document.querySelector("#autocomplete"),
  "YOUR_API_KEY",
  { placeholder: "Enter an address in Germany" }
);

autocomplete.addFilterByCountry(["de"]);

autocomplete.on("select", (feature) => {
  console.log(feature?.properties?.formatted);
});

Pass two or three codes to support a small multi-country service area:

autocomplete.addFilterByCountry(["de", "at"]);

Install the library with:

npm install @geoapify/geocoder-autocomplete