Address search can be used to search addresses and points of interest (POIs). An address is matched to its corresponding geographic coordinates and in the simplest search, you can provide only one parameter, the text you want to match in any part of the location details.
\nhttp://api.digitransit.fi/geocoding/v1/search
| Parameter | \nType | \nDescription | \n
|---|---|---|
text | \nstring | \nText to be searched | \n
size | \ninteger | \nLimits the number of results returned | \n
boundary.rect.min_lonboundary.rect.max_lonboundary.rect.min_latboundary.rect.max_lat | \nfloating point number | \nSearches using a boundary that is specified by a rectangle with latitude and longitude coordinates for two diagonals of the bounding box (the minimum and the maximum latitude, longitude). | \n
boundary.circle.latboundary.circle.lonboundary.circle.radius | \nfloating point number | \nSearches using location coordinates and a maximum distance radius within which acceptable results can be located. | \n
focus.point.latfocus.point.lon | \nfloating point number | \nScores the nearby places higher depending on how close they are to the focus point so that places with higher scores will appear higher in the results list. | \n
sources | \ncomma-delimited string array | \nFilters results by source. Value can be oa (DVV address data), osm (OpenStreetMap), nlsfi (National Land Survey), gtfs<feedid>, citybikes<network>. Here feedid refers to GTFS feed identifier e.g. hsl and network is the citybike network identifier e.g. smoove. | \n
layers | \ncomma-delimited string array | \nFilters results by layer (address, venue, street, stop, station, bikestation, neighbourhood, localadmin, region) | \n
lang | \nstring | \nReturns results in the preferred language if such a language-bound name version is available (value can be fi, sv or en). | \n
Note: You can find out the list of GTFS feed identifiers by querying OpenTripPlanner routing api, for example:
\n\n\n\n
Running this query returns the list of feed identifiers used in Finland and Estonia routing services.
\nVehicle rental network identifiers can be examined by querying all vehicle rental stations:
\n\n\n\n
The response contains an array called features. Each feature has a point geometry and properties listed below:
| Name | \nType | \nDescription | \n
|---|---|---|
id | \nstring | \n\n |
gid | \nstring | \nGlobal id that consists of a layer (such as address or country), an identifier for the original data source (such as openstreetmap or openaddresses), and an id for the individual record corresponding to the original source identifier, where possible. | \n
layer | \nstring | \nPlace type (e.g. address), see the list of possible values in the parameter specs above | \n
source | \nstring | \nData source, see the list of possible values in the parameter specs above | \n
source_id | \nstring | \n\n |
name | \nstring | \nA short description of the location, for example a business name, a locality name, or part of an address, depending on what is being searched for and what is returned. | \n
postalcode | \nnumber | \n\n |
postalcode_gid | \nstring | \n\n |
confidence | \nnumber | \nAn estimation of how accurately this result matches the query. Value 1 means perfect match. | \n
distance | \nnumber | \nA distance from the focus point if it is given (in kilometers) | \n
accuracy | \nstring | \nReturns always coordinates of just one point. If the object is originally an area or a line like a road, then the centroid is calculated (value can be point or centroid). | \n
country | \nstring | \nPlaces that issue passports, nations, nation-states | \n
country_gid | \nstring | \n\n |
country_a | \nstring | \nISO 3166-1 alpha-3 country code, for example FIN | \n
region | \nstring | \nFor example Uusimaa | \n
region_gid | \nstring | \n\n |
localadmin | \nstring | \nLocal administrative boundaries, for example Helsinki | \n
localadmin_gid | \nstring | \n\n |
locality | \nstring | \nTowns, hamlets, cities, for example Helsinki | \n
locality_gid | \nstring | \n\n |
neighbourhood | \nstring | \nSocial communities, neighbourhoods, for example Itä-Pasila | \n
neighbourhood_gid | \nstring | \n\n |
label | \nstring | \nA human-friendly representation of the place with the most complete details, that is ready to be displayed to an end user, for example East-West Pub, Itä-Pasila, Helsinki. | \n
Note: Not exactly the same fields are returned for all searches because all object locations do not have the same data available, for example neighborhood is not in use with all objects.
\n\n\nhttps://api.digitransit.fi/geocoding/v1/search?text=kamppi&size=1
\n
Note: Using parameter size=1 limits the number of results returned to one.
\n\n\nhttps://api.digitransit.fi/geocoding/v1/search?text=kamppi&layers=address
\n
Note: Using parameter layers=address returns results for places having text kamppi with a street address.
\n\n\n\n
\n\n\n
Note: Parameter boundary.circle.radius is always specified in kilometers.
\n\n\n\n
Note: Using parameter focus.point sorts equally matching places depending on how close they are to the focus point.
\nThe language preference can be defined using lang=xx parameter, default being lang=fi. Unlike in reverse\ngeocoding, the preference has significance for geocoding searches only when multiple languages provide\nan equally good match. An example:
\n\nhttps://api.digitransit.fi/geocoding/v1/search?text=finlandia&lang=sv&size=1
\n
\n\nhttps://api.digitransit.fi/geocoding/v1/search?text=finlandia&lang=fi&size=1
\n
The first search returns Finladia-huset, Helsingfors, and the second one Finlandia-talo, Helsinki.\nBoth match the search string finlandia equally well.
In most cases, an identified best match defines the language for the response, overruling the preference. An example:
\n\n\nhttps://api.digitransit.fi/geocoding/v1/search?text=ulrikasborg&lang=fi
\n
In this case, the search string matches perfectly a swedish place name, and consiquently the result is\n\"Ulrikasborg, Helsingfors\". In other words, the geocoding API does not act like a translation service.
\nNote: Part of the provided geocoding data does not include Swedish names, and part of the data\nleaves the language context unknown. This may occasionally cause unexpected errors in language selection.
","tableOfContents":"