Woosmap for Flutter - API Services
Get access to Woosmap services for your native mobile developments on hybrid flutter development.
The Woosmap API is a RESTful API built on HTTP. It has predictable resource URLs. It returns HTTP response codes to indicate errors. It also accepts and returns JSON in the HTTP body.
Localities API
Woosmap Localities API is a web service that returns a great amount of geographical places in response to an HTTP request. Among others are city names, postal codes, suburbs, addresses or airports. Request is done over HTTPS using GET. Response is formatted as JSON. You must specify a key in your request, included as the value of a key parameter for your public key or private_key for your private key. This key identifies your application for purposes of quota management.
-
Autocomplete for Localities
Autocomplete on worldwide suggestions for a for text-based geographic searches. It can match on full words as well as substrings. You can therefore send queries as the user types, to provide on-the-fly city names, postal codes or suburb name suggestions.
Request parameters
input
: The text string on which to search, for example: “london”types
: “locality” “postal_code” “address” “admin_level” “country” “airport” “train_station” “metro_station” “shopping” “museum” “tourist_attraction” “amusement_park” “art_gallery” “zoo” “town” “village” “hamlet” “borough” “suburb” “quarter” “neighborhood” “city”components
: A grouping of places to which you would like to restrict your results. Components can be used to filter over countries.language
: The language code, using ISO 3166-1 Alpha-2 country codes, indicating in which language the results should be returnedlocation
: This parameter is used to add a bias to the autocomplete feature. The location defines the point around which to retrieve results in priority.radius
: This parameter may be used in addition to the location parameter to define the distance in meters within which the API will return results in priority.data
: Two values for this parameter: standard or advanced. By default, if the parameter is not defined, value is set as standard. The advanced value opens suggestions to worldwide postal codes in addition to postal codes for Western Europe. A dedicated option subject to specific billing on your license is needed to use this parameter.extended
:If set, this parameter allows a refined search over locality names that bears the same postal code.customDescription
: This parameter allows to choose the description format for all or some of the suggestion types selected. The custom formats are described as follows (available fields depend on the returned type):custom_description=type_A:"{field_1}, {field_2}, [...]"|type_B:"{field_1}, {field_2}, [...]"
LocalitiesAutocompleteRequest request = LocalitiesAutocompleteRequest(
input: "87 Rue montmatre",
);
WoosmapApi woosmapApi = WoosmapApi(WoosKey(publicKey: "YOUR-PUBLIC-KEY"));
woosmapApi.localities.autocomplete(request).then((value) {
debugPrint(jsonEncode(value?.toJson()));
}).catchError((error) {
debugPrint("An error occurred: ${error.message}");
});
-
Details of a Locality
Provides details of an autocomplete suggestion (using the suggestion’s
publicId
).Request parameters
publicId
: A textual identifier that uniquely identifies a locality, returned from a Localities Autocomplete.language
: The language code, using ISO 3166-1 Alpha-2 country codes, indicating in which language the results should be returnedfields
: Used to limit the returning fields, default it is geometrycountryCodeFormat
: To specify the format for the short country code expected to be returned in the address_components field (default is alpha3).
LocalitiesDetailsRequest request = LocalitiesDetailsRequest(
publicId: "1234567890",
);
WoosmapApi woosmapApi = WoosmapApi(WoosKey(publicKey: "YOUR-PUBLIC-KEY"));
woosmapApi.localities.details(request).then((value) {
debugPrint(jsonEncode(value?.toJson()));
}).catchError((error) {
debugPrint("An error occurred: ${error.message}");
});
-
Geocode a locality or Reverse Geocode a latlng
Provides details for an address or a geographic position. Either parameter
address
orlatlng
is required.Request parameters
address
: The input string to geocode. Can represent an address, a street, a locality or a postal code.latLng
: The latlng parameter is used for reverse geocoding, it’s required if the address parameter is missing.components
: A grouping of places to which you would like to restrict your results. Components can be used to filter over countries. Countries must be passed as an ISO 3166-1 Alpha-2 or Alpha-3 compatible country code.language
: The language code, using ISO 3166-1 Alpha-2 country codes, indicating in which language the results should be returnedfields
: Used to limit the returning fieldsdata
: Two values for this parameter: standard or advanced. By default, if the parameter is not defined, value is set as standard. The advanced value opens suggestions to worldwide postal codes in addition to postal codes for Western Europe. A dedicated option subject to specific billing on your license is needed to use this parameter.countryCodeFormat
: To specify the format for the short country code expected to be returned in the address_components field.listSubBuildings
: Allows to retrieve all addresses at the same location for a common street number or building. WhenlistSubBuildings=true
and according to actual addresses at the provided location, results may contain an additional keysubBuildings
as a list of address summaries. It will provide apublicId
and adescription
for every address at the provided location (flats, organisations..).
LocalitiesGeocodeRequest request = LocalitiesGeocodeRequest(
address: "87 Rue montmatre",
);
WoosmapApi woosmapApi = WoosmapApi(WoosKey(publicKey: "YOUR-PUBLIC-KEY"));
woosmapApi.localities.geocode(request).then((value) {
debugPrint(jsonEncode(value?.toJson()));
}).catchError((error) {
debugPrint("An error occurred: ${error.message}");
});
-
Search for Localities
Provides a way to search for points of interest based on textual input and a geographical bias along with usual Localities supported types.
It can match both complete words and substrings. The retrieved locations are designed to assist users in selecting their desired place. To obtain additional details about a result, you must send a details request using its
publicId
.Request parameters
-
input
: The text string on which to search, for example: “london” or “123 Cross Road”. The Woosmap Localities API will return predictions matches based on this string and order the results based on their perceived relevance. -
location
: This parameter is used to add a geographical bias to the query. The location defines the point around which to retrieve results in priority. -
radius
: This parameter may be used in addition to the location parameter to define the distance in meters within which the API will return results in priority. Results outside of the defined area may still be displayed. Default radius if this parameter is not set is 100000. -
types
: The list of types of suggestion to return. Check full list of supported types here. -
components
: A grouping of places to which you would like to restrict your results. Countries must be passed as an ISO 3166-1 Alpha-2 compatible country code. -
language
: The language code, using ISO 639-2 Alpha-2 country codes, indicating in which language the results should be returned, if possible. Default is English i.e.en
.
-
LocalitiesSearchRequest request = LocalitiesSearchRequest(
input: "paris",
types: [LocalitiesTypes.address, LocalitiesTypes.locality],
components: LocalitiesComponentRestrictions(country: "fr"),
location: LatLng(lat: 48.85, lng: 2.35),
radius: 300,
language: "fr",
excludedTypes: [LocalitiesTypes.airport],
);
WoosmapApi woosmapApi = WoosmapApi(WoosKey(publicKey: "YOUR-PUBLIC-KEY"));
woosmapApi.localities.search(request).then((value) {
debugPrint(jsonEncode(value?.toJson()));
}).catchError((error) {
debugPrint("An error occurred: ${error.message}");
});
-
Nearby for Localities
Woosmap Localities Nearby allows you to look for points of interest within a defined area (latitude, longitude and a radius). You can narrow down your query by specifying the category you are seeking.
Request parameters
-
location
: The point around which to retrieve place information. -
radius
: This parameter may be used in addition to the location parameter to define the distance in meters within which the API will return results. When not specified, radius defaults to 1000 meters. -
type
: The types of suggestion to return. Currently, onlypoint_of_interest
is supported by Localities Nearby. More types will be included in future updates. Default value ispoint_of_interest
. -
categories
: A list ofLocalitiesNearbyCategories
. This allows you to specify the categories of points of interest that should be returned as suggestions. For list of categories check here. -
page
: Use page to navigate through paginated results. In the response, pagination object informs about a potential next page. -
limit
: Defines how many results should be included in single page. In case of navigation between pages, limit must not be updated. When not specified, limit defaults to 10 points of interest.
-
LocalitiesNearbyRequest request = LocalitiesNearbyRequest(
location: LatLng(lat: 48.85, lng: 2.35),
radius: 300,
type: LocalitiesNearbyTypes.pointOfInterest,
page: 1,
limit: 100,
categories: [LocalitiesNearbyCategories.businessShop, LocalitiesNearbyCategories.businessFoodAndDrinks],
);
WoosmapApi woosmapApi = WoosmapApi(WoosKey(publicKey: "YOUR-PUBLIC-KEY"));
woosmapApi.localities.nearby(request).then((value) {
debugPrint(jsonEncode(value?.toJson()));
}).catchError((error) {
debugPrint("An error occurred: ${error.message}");
});
Store Search API
Stores Search API lets you search among your own Points of Interest. Find stores by geography, by attributes or by autocomplete on store names.
-
Autocomplete for assets
Autocomplete on localizedNames with highlighted results on asset name. Use the field localized in your query parameter to search for localized names.
Request parameters
query
: Search query combining one or more search clauses. Example:query=name:'My cool store'|type:'click_and_collect'
language
: The preferred language to match against name (defaults on Accept-Language header)limit
: You can then request stores by page usinglimit
parameters
StoresAutocompleteRequest request = StoresAutocompleteRequest(
query: "name:'My cool store'|type:'click_and_collect'",
);
WoosmapApi woosmapApi = WoosmapApi(WoosKey(publicKey: "YOUR-PUBLIC-KEY"));
woosmapApi.stores.autocomplete(request).then((value) {
debugPrint(jsonEncode(value?.toJson()));
}).catchError((error) {
debugPrint("An error occurred: ${error.message}");
});
-
Search for assets
Used to retrieve assets from query.
Request parameters
query
: Search query combining one or more search clauses. Example:query=name:'My cool store'|type:'click_and_collect'
latLng
: To bias the results around a specific latlngradius
: To bias the results within a given circular area.polyline
: Find stores nearby an encoded polyline and inside a defined radius.storesByPage
: You can then request stores by page usingpage
andstoresByPage
parameters (Default is 100, max is 300).page
: Page number when accessing paginated storeszone
: whether to search for stores intersecting a zone
StoresSearchRequest request = StoresSearchRequest(
query: "idStore:31625406",
);
WoosmapApi woosmapApi = WoosmapApi(WoosKey(publicKey: "YOUR-PUBLIC-KEY"));
woosmapApi.stores.search(request).then((value) {
debugPrint(jsonEncode(value?.toJson()));
}).catchError((error) {
debugPrint("An error occurred: ${error.message}");
});
Distance API
Distance APIs Is a set of APIs that provide distances, durations, routing and tolls information between start and end points. It can also be make isochrone calculations from a starting point.
-
Distance Matrix
Get distances and durations for a matrix of origins and destinations, based on the recommended route between start and end points for a specified travel mode. Accepts
DistanceMatrixRequest
object and returns an object ofDistanceMatrixResponse
which has arows
collection containing distance and duration values for each pair of start and end point. The returned distances are designed to be used to find and sort multiple assets by road distance. Duration values are either based on average speed, or with traffic awareness according to request parameters.Request parameters
origins
: An array containing origins LatLng from which to calculate distance and time.destinations
: An array containing destinations LatLng to which to calculate distance and time.method
: Defines the method to compute the route between the start point and the end point. Valid values are ‘time’ for the fastest route and ‘distance’ for the shortest route.elements
: Defines element values that will be part of the response (distance and/or duration). If not specified, the default is ‘distance’.departureTime
: Specifies the date/time at which to base the calculations on for traffic purposes. Valid values are unix epoch time string or the string ‘now’.language
: The language code indicating the language in which the results should be returned.travelMode
: Specifies the travel mode. Valid values are ‘driving’, ‘walking’, or ‘cycling’.unitSystem
: The unit system used for distance measurement. Default ismetric
, the other option isimperial
avoidFerries
: If true, instructs the Distance service to avoid ferries where possible.avoidHighways
: If true, instructs the Distance service to avoid highways where possible.avoidTolls
: If true, instructs the Distance service to avoid toll roads where possible.avoidZones
: If set, instructs the Distance service to avoid the specific polygons.
DistanceMatrixRequest request = DistanceMatrixRequest(
origins: [LatLng(lat: 19.21034471165546, lng: 72.86760122219786)],
destinations: [LatLng(lat: 18.99344303927699, lng: 72.82514876796016)],
unitSystem: UnitSystem.metric,
language: "fr",
travelMode: DistanceTravelMode.driving,
elements: DistanceElement.duration,
method: DirectionMethod.distance,
avoidTolls: true,
avoidFerries: true,
avoidZones: [
[
LatLng(lat: 19.072569055840898, lng: 72.84112306577242),
LatLng(lat: 19.07131188628528, lng: 72.85241063283135),
LatLng(lat: 19.058811510269383, lng: 72.85301871725203),
LatLng(lat: 19.059637713632224, lng: 72.84142710798275),
]
],
departureTime: "now",
);
WoosmapApi woosmapApi = WoosmapApi(WoosKey(publicKey: "YOUR-PUBLIC-KEY"));
woosmapApi.distance.distanceMatrix(request).then((value) {
debugPrint(jsonEncode(value?.toJson()));
}).catchError((error) {
debugPrint("An error occurred: ${error.message}");
});
-
Route
Get distance, duration and path (as a polyline) between an origin and a destination, based on the recommended route between those two points for a specified travel mode. You can either retrieve duration values based on average speed, or with traffic awareness according to request parameters. Accepts
DistanceRouteRequest
object and returnsDistanceRouteResponse
which hasroutes
collection.Request parameters
origin
: The starting point in latitude/longitude coordinates.destination
: The ending point in latitude/longitude coordinates.mode
: Specifies the mode of transport to use when calculating distance.DistanceTravelMode
enum with possible valuedriving
,walking
,cycling
.language
: The language code indicating the language in which the results should be returned.unitSystem
: Specifies the unit system parameter to use when expressing distance.provideRouteAlternatives
: Specifies if alternative routes should be returned. Default is false.waypoints
: A list of waypoints along the route.method
: Specifies the method to compute the route:time
(fastest) ordistance
(shortest).details
: Specifies if maneuver instructions should be returned. Default is ‘none’.departureTime
: Specifies the departure time for real-time traffic calculations. Use either Unix epoch string or the stringnow
.arrivalTime
: Specifies the arrival time. Use eitherarrivalTime
ordepartureTime
, not both. Use Unix epoch string.avoidFerries
: If true, instructs the Distance service to avoid ferries where possible.avoidHighways
: If true, instructs the Distance service to avoid highways where possible.avoidTolls
: If true, instructs the Distance service to avoid toll roads where possible.avoidZones
: If set, instructs the Distance service to avoid the specific polygons.
DistanceRouteRequest request = DistanceRouteRequest(
origin: LatLngLiteral(lat: 19.21034471165546, lng: 72.86760122219786),
destination:
LatLngLiteral(lat: 18.99344303927699, lng: 72.82514876796016),
mode: DistanceTravelMode.driving,
details: DistanceRouteDetails.full,
method: DirectionMethod.distance,
language: "fr",
unitSystem: UnitSystem.metric,
waypoints: DistanceWaypoints(points: [
LatLngLiteral(lat: 19.061313061301266, lng: 72.85127892689086)
], optimize: true),
avoidFerries: true,
avoidHighways: false,
avoidTolls: true,
avoidZones: [
[
LatLng(lat: 19.072569055840898, lng: 72.84112306577242),
LatLng(lat: 19.07131188628528, lng: 72.85241063283135),
LatLng(lat: 19.058811510269383, lng: 72.85301871725203),
LatLng(lat: 19.059637713632224, lng: 72.84142710798275),
]
],
departureTime: "now",
provideRouteAlternatives: true);
WoosmapApi woosmapApi = WoosmapApi(WoosKey(publicKey: "YOUR-PUBLIC-KEY"));
woosmapApi.distance.route(request).then((value) {
debugPrint(jsonEncode(value?.toJson()));
}).catchError((error) {
debugPrint("An error occurred: ${error.message}");
});
-
Tolls
Get Toll costs, Toll details, distance, duration and path (as a polyline) between an origin and a destination, based on the recommended route between those two points by car. This endpoint provides you all the information needed to get tolls pricing and details for an itinerary. Accepts
DistanceTollsRequest
object and returnsDistanceTollsResponse
containingDistanceTollRoute
object collection.Request parameters
origin
: The origin of the route.destination
: The destination of the route.language
: The language code indicating the language in which the results should be returned.unitSystem
: Specifies the unit system parameter to use when expressing distance.method
: Specifies the method to compute the route:time
(fastest) ordistance
(shortest).provideRouteAlternatives
: Specifies if alternative routes should be returned. Default is false.waypoints
: A list of waypoints along the route.optimize:true
parameter is not supported on the /tolls endpoint.departureTime
: Specifies the departure time for real-time traffic calculations. Use either Unix epoch string or the stringnow
.arrivalTime
: Specifies the arrival time. Use eitherarrivalTime
ordepartureTime
, not both. Use Unix epoch string.
DistanceTollsRequest request = DistanceTollsRequest(
origin: LatLngLiteral(lat: 19.211813550966852, lng: 72.86491576857733),
destination:
LatLngLiteral(lat: 18.248663602443713, lng: 73.87807476531295),
language: "en",
unitSystem: UnitSystem.metric,
arrivalTime: "1742365749");
WoosmapApi woosmapApi = WoosmapApi(WoosKey(publicKey: "YOUR-PUBLIC-KEY"));
woosmapApi.distance.tolls(request).then((value) {
debugPrint(jsonEncode(value?.toJson()));
}).catchError((error) {
debugPrint("An error occurred: ${error.message}");
});
-
Isochrone
Calculates Distance Isochrone. An isochrone is a line that connects points of equal travel time or distance around a given location. The isochrone endpoint computes areas that are reachable within a specified amount of time or distance from a location, and returns the reachable regions as contours of lines that you can display on a map. Accepts
DistanceIsochroneRequest
object and returnsDistanceIsochroneResponse
.Request parameters
origin
: The starting point in latitude/longitude coordinates.value
: The value for the isochrone contour (time in minutes or distance in kilometers). The maximum allowed value is 120.mode
: Specifies the mode of transport to use when calculating the isochrone.language
: The language code indicating the language in which the results should be returned.unitSystem
: Specifies the unit system parameter to use when expressing distance.method
: Specifies the method to compute the route:time
(fastest) ordistance
(shortest).avoidFerries
: If true, instructs the Distance service to avoid ferries where possible.avoidHighways
: If true, instructs the Distance service to avoid highways where possible.avoidTolls
: If true, instructs the Distance service to avoid toll roads where possible.avoidZones
: If set, instructs the Distance service to avoid the specific polygons.
DistanceIsochroneRequest request = DistanceIsochroneRequest(
origin: LatLngLiteral(lat: 19.061313061301266, lng: 72.85127892689086),
value: 12,
method: DirectionMethod.time,
mode: DistanceTravelMode.driving,
unitSystem: UnitSystem.imperial,
avoidHighways: true,
avoidTolls: true,
language: "fr");
WoosmapApi woosmapApi = WoosmapApi(WoosKey(publicKey: "YOUR-PUBLIC-KEY"));
woosmapApi.distance.isochrone(request).then((value) {
debugPrint(jsonEncode(value?.toJson()));
}).catchError((error) {
debugPrint("An error occurred: ${error.message}");
});
Transit API
Transit API uses data provided by transit agencies (real time, timetables, average travel times) to build itineraries. In addition pedestrian mode can be proposed in itineraries to reach starting and ending points and commute between transportation modes
Route
Get distance, duration, path and public transport details between an origin and a destination, based on public transportation between those two points. This endpoint provides all the information needed to evaluate an itinerary.
Request parameters
origin
: The starting point for the route. It should be supplied in the form of latitude/longitude.destination
: The ending point for the route. It should be supplied in the form of latitude/longitude.arrivalTime
?: Specifies the date/time at which to base the calculations on for transit route.departureTime
?: Specifies the date/time at which to base the calculations on for transit route.modes
?: Transit mode filter used to determine which modes of transit to include in the response. By default, all supported transit modes are permitted. Supported modes:highSpeedTrain
intercityTrain
interRegionalTrain
regionalTrain
cityTrain
bus
ferry
subway
lightRail
privateBus
inclined
aerial
busRapid
monorail
flight
This parameter also support an exclusion list: It’s sufficient to specify each mode to exclude by prefixing it with-
. Mixing of inclusive and exclusive transit modes is not allowed.
TransitRouteRequest request = TransitRouteRequest(
origin: LatLngLiteral(lat: 45.467, lng: 9.0516),
destination: LatLngLiteral(lat: 45.4599, lng: 9.2822),
mode: [
'highSpeedTrain',
'intercityTrain',
'interRegionalTrain',
'regionalTrain',
'cityTrain',
'bus',
'ferry',
'subway',
'lightRail',
'privateBus',
'inclined',
'aerial',
'busRapid',
'monorail',
'flight'
],
departureTime: null,
arrivalTime: null);
WoosmapApi woosmapApi = WoosmapApi(WoosKey(
privateKey: Platform.isAndroid
? AppConstants.of(context)?.privateKeyAndroid ?? ""
: AppConstants.of(context)?.privateKeyiOS ?? "",
));
woosmapApi.transit.route(request).then((value) {
debugPrint(jsonEncode(value?.toJson()));
}).catchError((error) {
debugPrint("An error occurred: ${error.message}");
});