com.nbmap.api.geocoding.v5

Class NbmapGeocoding.Builder

java.lang.Object

com.nbmap.api.geocoding.v5.NbmapGeocoding.Builder

Enclosing class:

NbmapGeocoding

public abstract static class NbmapGeocoding.Builder
extends java.lang.Object

This builder is used to create a new request to the Nbmap Geocoding API. At a bare minimum, your request must include an access token and a query of some kind. All other fields can be left alone in order to use the default behaviour of the API.

By default, the geocoding mode is set to nbmap.places. The mode can be changed to nbmap.places-permanent to enable batch and permanent geocoding. For more information about nbmap.places-permanent, contact Nbmap sales.

Note to contributors: All optional booleans in this builder use the object Boolean rather than the primitive to allow for unset (null) values.

Since:

1.0.0

Constructor Summary

Constructors

Constructor and Description
Builder()

Method Summary

Modifier and Type	Method and Description
abstract NbmapGeocoding.Builder	accessToken(java.lang.String accessToken) Required to call when this is being built.
abstract NbmapGeocoding.Builder	autocomplete(java.lang.Boolean autocomplete) This controls whether autocomplete results are included.
abstract NbmapGeocoding.Builder	baseUrl(java.lang.String baseUrl) Optionally change the APIs base URL to something other then the default Nbmap one.
NbmapGeocoding.Builder	bbox(com.nbmap.geojson.BoundingBox bbox) Limit the results to a defined bounding box.
NbmapGeocoding.Builder	bbox(double minX, double minY, double maxX, double maxY) Limit the results to a defined bounding box.
NbmapGeocoding.Builder	bbox(com.nbmap.geojson.Point southwest, com.nbmap.geojson.Point northeast) Limit the results to a defined bounding box.
abstract NbmapGeocoding.Builder	bbox(java.lang.String bbox) Limit the results to a defined bounding box.
NbmapGeocoding	build() Build a new NbmapGeocoding object.
abstract NbmapGeocoding.Builder	clientAppName(java.lang.String clientAppName) Base package name or other simple string identifier.
NbmapGeocoding.Builder	country(java.util.Locale country) Add a single country locale to restrict the results.
NbmapGeocoding.Builder	country(java.lang.String... country) Limit results to one or more countries.
abstract NbmapGeocoding.Builder	country(java.lang.String country) Limit results to one or more countries.
abstract NbmapGeocoding.Builder	fuzzyMatch(java.lang.Boolean fuzzyMatch) Specify whether the Geocoding API should attempt approximate, as well as exact, matching when performing searches (true, default), or whether it should opt out of this behavior and only attempt exact matching (false).
NbmapGeocoding.Builder	geocodingTypes(java.lang.String... geocodingTypes) This optionally can be set to filter the results returned back after making your forward or reverse geocoding request.
NbmapGeocoding.Builder	intersectionStreets(java.lang.String streetOneName, java.lang.String streetTwoName) Specify the two street names for intersection search.
NbmapGeocoding.Builder	languages(java.util.Locale... languages) This optionally specifies the desired response language for user queries.
abstract NbmapGeocoding.Builder	languages(java.lang.String languages) This optionally specifies the desired response language for user queries.
NbmapGeocoding.Builder	limit(int limit) This optionally specifies the maximum number of results to return.
abstract NbmapGeocoding.Builder	mode(java.lang.String mode) This sets the kind of geocoding result you desire, either ephemeral geocoding or batch geocoding.
NbmapGeocoding.Builder	proximity(com.nbmap.geojson.Point proximity) Bias local results base on a provided Point.
NbmapGeocoding.Builder	query(com.nbmap.geojson.Point point) Perform a reverse geocode on the provided Point.
abstract NbmapGeocoding.Builder	query(java.lang.String query) This method can be used for performing a forward geocode on a string representing a address or POI.
abstract NbmapGeocoding.Builder	reverseMode(java.lang.String reverseMode) Set the factors that are used to sort nearby results.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Builder

public Builder()

Method Detail

query

public NbmapGeocoding.Builder query(@NonNull
                                    com.nbmap.geojson.Point point)

Perform a reverse geocode on the provided Point. Only one point can be passed in as the query and isn't guaranteed to return a result. If you want to do a batch reverse Geocode, you can use the query(String) method separating them with a semicolon. For more information about batch geocoding, contact Nbmap sales.

Parameters:

point - a GeoJSON point which matches to coordinate you'd like to reverse geocode

Returns:

this builder for chaining options together

Since:

3.0.0

query

public abstract NbmapGeocoding.Builder query(@NonNull
                                             java.lang.String query)

This method can be used for performing a forward geocode on a string representing a address or POI. If you want to perform a batch geocode, separate your queries with a semicolon. For more information about batch geocoding, contact Nbmap sales.

Parameters:

query - a String containing the text you'd like to forward geocode

Returns:

this builder for chaining options together

Since:

3.0.0

mode

public abstract NbmapGeocoding.Builder mode(@NonNull
                                            java.lang.String mode)

This sets the kind of geocoding result you desire, either ephemeral geocoding or batch geocoding.

To access batch geocoding, contact Nbmap sales. If you do not have access to batch geocoding, it will return an error code rather than a successful result.

Options avaliable to pass in include, GeocodingCriteria.MODE_PLACES for a ephemeral geocoding result (default) or GeocodingCriteria.MODE_PLACES_PERMANENT for batch and permanent geocoding.

Parameters:

mode - nbmap.places or nbmap.places-permanent for batch and permanent geocoding

Returns:

this builder for chaining options together

Since:

1.0.0

proximity

public NbmapGeocoding.Builder proximity(@NonNull
                                        com.nbmap.geojson.Point proximity)

Bias local results base on a provided Point. This oftentimes increases accuracy in the returned results.

Parameters:

proximity - a point defining the proximity you'd like to bias the results around

Returns:

this builder for chaining options together

Since:

1.0.0

geocodingTypes

public NbmapGeocoding.Builder geocodingTypes(@NonNull
                                             java.lang.String... geocodingTypes)

This optionally can be set to filter the results returned back after making your forward or reverse geocoding request. A null value can't be passed in and only values defined in GeocodingCriteria.GeocodingTypeCriteria are allowed.

Note that GeocodingCriteria.TYPE_POI_LANDMARK returns a subset of the results returned by GeocodingCriteria.TYPE_POI. More than one type can be specified.

Parameters:

geocodingTypes - optionally filter the result types by one or more defined types inside the GeocodingCriteria.GeocodingTypeCriteria

Returns:

this builder for chaining options together

Since:

1.0.0

country

public NbmapGeocoding.Builder country(java.util.Locale country)

Add a single country locale to restrict the results. This method can be called as many times as needed inorder to add multiple countries.

Parameters:

country - limit geocoding results to one

Returns:

this builder for chaining options together

Since:

3.0.0

country

public NbmapGeocoding.Builder country(java.lang.String... country)

Limit results to one or more countries. Options are ISO 3166 alpha 2 country codes separated by commas.

Parameters:

country - limit geocoding results to one

Returns:

this builder for chaining options together

Since:

3.0.0

country

public abstract NbmapGeocoding.Builder country(java.lang.String country)

Limit results to one or more countries. Options are ISO 3166 alpha 2 country codes separated by commas.

Parameters:

country - limit geocoding results to one

Returns:

this builder for chaining options together

Since:

3.0.0

autocomplete

public abstract NbmapGeocoding.Builder autocomplete(java.lang.Boolean autocomplete)

This controls whether autocomplete results are included. Autocomplete results can partially match the query: for example, searching for washingto could include washington even though only the prefix matches. Autocomplete is useful for offering fast, type-ahead results in user interfaces.

If your queries represent complete addresses or place names, you can disable this behavior and exclude partial matches by setting this to false, the defaults true.

Parameters:

autocomplete - optionally set whether to allow returned results to attempt prediction of the full words prior to the user completing the search terms

Returns:

this builder for chaining options together

Since:

1.0.0

bbox

public NbmapGeocoding.Builder bbox(com.nbmap.geojson.BoundingBox bbox)

Limit the results to a defined bounding box. Unlike NbmapGeocoding.proximity(), this will strictly limit results to within the bounding box only. If simple biasing is desired rather than a strict region, use proximity instead.

Parameters:

bbox - the bounding box as a BoundingBox

Returns:

this builder for chaining options together

Since:

4.7.0

bbox

public NbmapGeocoding.Builder bbox(com.nbmap.geojson.Point southwest,
                                   com.nbmap.geojson.Point northeast)

Limit the results to a defined bounding box. Unlike NbmapGeocoding.proximity(), this will strictly limit results to within the bounding box only. If simple biasing is desired rather than a strict region, use proximity instead.

Parameters:

northeast - the northeast corner of the bounding box as a Point

southwest - the southwest corner of the bounding box as a Point

Returns:

this builder for chaining options together

Since:

1.0.0

bbox

public NbmapGeocoding.Builder bbox(double minX,
                                   double minY,
                                   double maxX,
                                   double maxY)

Limit the results to a defined bounding box. Unlike NbmapGeocoding.proximity(), this will strictly limit results to within the bounding box only. If simple biasing is desired rather than a strict region, use proximity instead.

Parameters:

minX - the minX of bounding box when maps facing north

minY - the minY of bounding box when maps facing north

maxX - the maxX of bounding box when maps facing north

maxY - the maxY of bounding box when maps facing north

Returns:

this builder for chaining options together

Since:

1.0.0

bbox

public abstract NbmapGeocoding.Builder bbox(@NonNull
                                            java.lang.String bbox)

Limit the results to a defined bounding box. Unlike NbmapGeocoding.proximity(), this will strictly limit results to within the bounding box only. If simple biasing is desired rather than a strict region, use proximity instead.

Parameters:

bbox - a String defining the bounding box for biasing results ordered in minX,minY,maxX,maxY

Returns:

this builder for chaining options together

Since:

1.0.0

limit

public NbmapGeocoding.Builder limit(int limit)

This optionally specifies the maximum number of results to return. For forward geocoding, the default is 5 and the maximum is 10. For reverse geocoding, the default is 1 and the maximum is 5. If a limit other than 1 is used for reverse geocoding, a single types option must also be specified.

Parameters:

limit - the number of returned results

Returns:

this builder for chaining options together

Since:

2.0.0

languages

public NbmapGeocoding.Builder languages(java.util.Locale... languages)

This optionally specifies the desired response language for user queries. For forward geocodes, results that match the requested language are favored over results in other languages. If more than one language tag is supplied, text in all requested languages will be returned. For forward geocodes with more than one language tag, only the first language will be used to weight results.

Any valid IETF language tag can be submitted, and a best effort will be made to return results in the requested language or languages, falling back first to similar and then to common languages in the event that text is not available in the requested language. In the event a fallback language is used, the language field will have a different value than the one requested.

Translation availability varies by language and region, for a full list of supported regions, see the link provided below.

Parameters:

languages - one or more locale's specifying the language you'd like results to support

Returns:

this builder for chaining options together

Since:

2.0.0

See Also:

Supported languages

languages

public abstract NbmapGeocoding.Builder languages(java.lang.String languages)

This optionally specifies the desired response language for user queries. For forward geocodes, results that match the requested language are favored over results in other languages. If more than one language tag is supplied, text in all requested languages will be returned. For forward geocodes with more than one language tag, only the first language will be used to weight results.

Any valid IETF language tag can be submitted, and a best effort will be made to return results in the requested language or languages, falling back first to similar and then to common languages in the event that text is not available in the requested language. In the event a fallback language is used, the language field will have a different value than the one requested.

Translation availability varies by language and region, for a full list of supported regions, see the link provided below.

Parameters:

languages - a String specifying the language or languages you'd like results to support

Returns:

this builder for chaining options together

Since:

2.0.0

See Also:

Supported languages

reverseMode

public abstract NbmapGeocoding.Builder reverseMode(@Nullable
                                                   java.lang.String reverseMode)

Set the factors that are used to sort nearby results. Options avaliable to pass in include, GeocodingCriteria.REVERSE_MODE_DISTANCE for nearest feature result (default) or GeocodingCriteria.REVERSE_MODE_SCORE the notability of features within approximately 1 kilometer of the queried point along with proximity.

Parameters:

reverseMode - limit geocoding results based on the reverseMode

Returns:

this builder for chaining options together

Since:

3.3.0

fuzzyMatch

public abstract NbmapGeocoding.Builder fuzzyMatch(java.lang.Boolean fuzzyMatch)

Specify whether the Geocoding API should attempt approximate, as well as exact, matching when performing searches (true, default), or whether it should opt out of this behavior and only attempt exact matching (false). For example, the default setting might return Washington, DC for a query of wahsington, even though the query was misspelled.

Parameters:

fuzzyMatch - optionally set whether to allow the geocoding API to attempt exact matching or not.

Returns:

this builder for chaining options together

Since:

4.9.0

accessToken

public abstract NbmapGeocoding.Builder accessToken(@NonNull
                                                   java.lang.String accessToken)

Required to call when this is being built. If no access token provided, ServicesException will be thrown.

Parameters:

accessToken - Nbmap access token, You must have a Nbmap account inorder to use the Geocoding API

Returns:

this builder for chaining options together

Since:

1.0.0

clientAppName

public abstract NbmapGeocoding.Builder clientAppName(@NonNull
                                                     java.lang.String clientAppName)

Base package name or other simple string identifier. Used inside the calls user agent header.

Parameters:

clientAppName - base package name or other simple string identifier

Returns:

this builder for chaining options together

Since:

1.0.0

baseUrl

public abstract NbmapGeocoding.Builder baseUrl(@NonNull
                                               java.lang.String baseUrl)

Optionally change the APIs base URL to something other then the default Nbmap one.

Parameters:

baseUrl - base url used as end point

Returns:

this builder for chaining options together

Since:

1.0.0

intersectionStreets

public NbmapGeocoding.Builder intersectionStreets(@NonNull
                                                  java.lang.String streetOneName,
                                                  @NonNull
                                                  java.lang.String streetTwoName)

Specify the two street names for intersection search.

Parameters:

streetOneName - First street name of the intersection

streetTwoName - Second street name of the intersection

Returns:

this builder for chaining options together

Since:

4.9.0

build

public NbmapGeocoding build()

Build a new NbmapGeocoding object.

Returns:

a new NbmapGeocoding using the provided values in this builder

Since:

3.0.0