Forward Geocoding API reference

Forward Geocoding is the process of converting an address or textual description of a location (street, city, landmark...) into its corresponding geographic coordinates (latitude and longitude).

While both search and autocomplete are supported as forward geocoding, they serve distinct purposes and offer different user experiences. search requires a complete address or location query, while autocomplete accepts partial queries as the user types.

Most of the time, autocomplete will be enough for your use case, so we suggest you to use it.

If you have opted to use this API on your website with real-time search, we suggest you implement throttling or use our library Places JS.

When should I use Forward Geocoding?

• You have a single address field that needs geographic coordinates:
  • Whether it is addresses written directly by your users or addresses stored in databases, write the address in the text parameter.
• You have an address split into its constituent parts:
  • You can merge them in the form address, city, country in the text parameter.
• You have users typing into a search box and need suggestions:
  • Send your request using the text parameter and check the label attribute.

Parameters

In our API, all the configuration is done through query parameters. You can change the path from autocomplete to search for forward geocoding.

https://api.jawg.io/places/v1/autocomplete?text=Paris&access-token=your-jawg-access-token
\___/   \_________/\_____/\__/\__________/\________/               \____________________/
  |          |        |     \       |         |                               |
scheme     domain service version  path     query                   authentication token

💡 Explore our interactive examples. The left input shows the result using the current configuration, while the right input displays the result with default settings.

access-token

The access token you receive after having an account on our services.

Not registered yet? Create your account now https://www.jawg.io/lab/.

boundary.circle

The boundary.circle.* parameters are used to constrain search results to a specific circular geographic area. This is useful when you want to limit the search to a particular circular region. You have to set one point (longitude and latitude) with a radius (in km).

In this example, we are restricting results in a circle and the parameters used are:

• boundary.circle.lat: 46.842269
• boundary.circle.lon: 2.39985
• boundary.circle.radius: 500

➡️ Returns only locations within the 500km circle radius.

boundary.country

The boundary.country parameter is used to constraint search results to specific countries (one or many). This is useful when you want to limit the search to some particular countries.

The value must be a comma separated list of alpha-2 or alpha-3 ISO-3166 country code, e.g. FR,USA for France and United States.

In this example, we are restricting results in Belgium and the parameter used is:

• boundary.country: BE

➡️ Returns only locations within Belgium.

boundary.gid

The boundary.gid parameter is used to constraint search results to a specific area (one or many) identified by the Geocoding Identifier of an administrative area. You can get the GID from any response of our API. This is useful when you want to limit the search to some particular regions.

• boundary.gid: whosonfirst:region:85672093

➡️ Returns locations only within Yogyakarta, Indonesia.

boundary.rect

The boundary.rect.* parameters are used to constrain search results to a specific rectangular geographic area. This is useful when you want to limit the search to a particular BBox/region. You have to set two points, the minimum and maximum longitude and latitude.

In this example, we are restricting results in a BBox and the parameters used are:

• boundary.rect.min_lat: 43.032582
• boundary.rect.min_lon: 5.097656
• boundary.rect.max_lat: 49.006466
• boundary.rect.max_lon: 26.762695

➡️ Returns locations only within the rectangle over Austria, Switzerland, Slovakia, Italia...

focus.country

The focus.country parameter is used to prioritize search results to specific countries (one or many). This is useful when you want to focus the search to some particular countries.

The value must be a comma separated list of alpha-2 or alpha-3 ISO-3166 country code, e.g. FR,USA for France and United States.

In this example, we are prioritizing results in Belgium and the parameter used is:

• focus.country: BE

➡️ Returns locations and give preference to those located in Belgium.

focus.gid

The focus.gid parameter is used to prioritize search results to a specific area (one or many) identified by the Geocoding Identifier of an administrative area. You can get the GID from any response of our API. This is useful when you want to focus the search to some particular regions.

• focus.gid: whosonfirst:region:85672093

➡️ Returns locations and give preference to those located in Yogyakarta, Indonesia.

focus.point

The focus.point.* parameters are used to prioritize search results to a specific 50km circular geographic area. This is useful when you want to focus the search nearby a particular point. You have to set one point (longitude and latitude).

• focus.point.lat: 48.877578
• focus.point.lon: 2.328132

➡️ Returns locations and give preference to those located in 50km radius from the point.

lang

The lang parameter is used to specify the targeted language for your results using the IETF BCP 47 language tag. By default, the API will use the user's browser language (thanks to Accept-Language HTTP header) and defaults to English.

When the translation is not available in your language, it will return the name in the local dialect or English.

➡️ Returns locations in German.

layers

The layers parameter is used to constraint the search to particular layers (one or many). Depending on your use-case, this can be very useful, for example if you need only addresses you can use layers=address, or only administrative area (country, cities, neighbourhood...) layers=coarse or everything except administrative area layers=address,street,venue.

Here is the full list of our layers:

➡️ Returns administrative locations, that means it removes all POIs, addresses and streets.

size

The size parameter restrict the number of returned locations. The default number of returned locations is 10 and the maximum is 40.

➡️ Returns only 2 locations.

sources

The sources parameter is used to constraint the search to particular sources (one or many). This can be useful if you want to control the returned data that will be displayed on your map.

⚠️ Using this parameter is not recommended, we are updating our sources and you may never enjoy our new features.

➡️ Returns locations from OpenAddresses.