Geocoder APIdocumentation.developer.here.com/pdf/geocoding_nlp/6.2.53... · 2019-07-10 · Reverse...
Transcript of Geocoder APIdocumentation.developer.here.com/pdf/geocoding_nlp/6.2.53... · 2019-07-10 · Reverse...
Geocoder APIRelease Notes
Version 6.2.53
Geocoder API Release Notes 2► Contents
Contents
Legal Notices..........................................................................................................................................................3
Document Information.................................................................................................................................... 4
Chapter 1: Overview................................................................................................................................. 5D44 Highlights.................................................................................................................................................6
Chapter 2: Release Major Changes............................................................................................ 7API Changes......................................................................................................................................................8
Retrieval of Landmarks.....................................................................................................................8
Suppression of Unnamed Links....................................................................................................12
Aggregation of Road Link Matches (gen=5).............................................................................. 13
Complete List of API Generations................................................................................................14
Map Data Version......................................................................................................................................... 15
Chapter 3: D44 Issues.........................................................................................................................17Resolved Issues and Enhancements........................................................................................................18
Known Issues.................................................................................................................................................22
Geocoder API Release Notes 3► Legal Notices
Legal Notices© 2014 HERE. All rights reserved.
This material, including documentation and any related computer programs, is protected by
copyright controlled by HERE. All rights are reserved. Copying, including reproducing, storing,
adapting or translating, any or all of this material requires the prior written consent of HERE. This
material also contains confidential information, which may not be disclosed to others without the
prior written consent of HERE.
Trademark Acknowledgements
HERE and Nokia are trademarks or registered trademarks of Nokia Corporation in the United States
and other countries.
Other trade names are trademarks or registered trademarks of their owners.
Disclaimer
This content is provided "as-is" and without warranties of any kind, either express or implied,
including, but not limited to, the implied warranties of merchantability, fitness for a particular
purpose, satisfactory quality and non-infringement. Nokia does not warrant that the content is error
free and Nokia does not warrant or make any representations regarding the quality, correctness,
accuracy, or reliability of the content. You should therefore verify any information contained in the
content before acting on it.
To the furthest extent permitted by law, under no circumstances, including without limitation Nokia's
negligence, shall Nokia be liable for any damages, including, without limitation, direct, special,
indirect, punitive, consequential, exemplary and/ or incidental damages that result from the use or
application of this content, even if Nokia or an authorized representative has been advised of the
possibility of such damages.
Geocoder API Release Notes 4► Document Information
Document Information
Product
Name: Geocoder API
Version: Version 6.2.53
Document
Name: Geocoder API Release Notes
Id: 0b27fb5-1398445254
Status: FINAL
Date: 2014-Apr-25, 17:02 (GMT)
Geocoder API Release Notes 5► Overview
Chapter
1
OverviewTopics:
• D44 Highlights
The scope of this document is to provide the release notes for the
Geocoder API for a particular release version. It also includes the
issues resolved and issues remaining in this release.
Geocoder API Release Notes 6► Overview
D44 Highlights• Map update for China, Hong Kong, Macau to 2013Q3
• Additional landmarks such as parks, lakes, islands and other natural features added to reversegeocoder
• Match quality and result rendering improvements for Turkey and South Africa. Newly designeduse of zone information
• Better support for street type abbreviations in Mexico
• Match quality improvements in Vietnam by considering country specific conventions
• Other bug fixes
Geocoder API Release Notes 7► Release Major Changes
Chapter
2
Release Major ChangesTopics:
• API Changes
• Map Data Version
This section documents major changes to the release that may
require users to change their applications and/or associated map
data.
Geocoder API Release Notes 8► Release Major Changes
API ChangesSome API enhancements and changes are coming with D44:
• Retrieval of landmarks such as parks, lakes, and other area features with new Reverse Geocoder
modes "retrieveLandmarks" and "retrieveAll"
• Supression of unnamed links from Reverse Geocoder responses
• gen=5: Strict country filter in Reverse Geocoder (bug fix), aggregation of road link matches in
Reverse Geocoder, changes in LocationType
Retrieval of LandmarksBesides address and admin area information client applications can now use the Reverse Geocoder to
retrieve landmarks such as parks, lakes, and other area features.
Usage: Request
Two additional mode parameter values were added: retrieveLandmarks and retrieveAll
Example: reversegeocode.xml?mode=retrieveAll&prox=37.80358,-122.44832
Usage: Response
For mode=retrieveAll the response contains
• All intersecting links/street segments (similar to retrieveAddresses)
• Admin hierarchy at request coordinate
• All intersecting area features (parks, lakes, etc.)
Ranking/Sorting
Results are sorted by distance. Equidistant areas are sorted by their size (smaller first).
• The distance for a polygon based match is the distance in meters between the input coordinate
and the boundary of the area
• For area matches that cover the input coordinate the distance is negative
• Polyline and point based matches use the existing distance calculation
Result Structure
Area features including landmarks are exposed as Location using the attribution listed below. The
Name attribute is new. It is currently only used for landmarks.
Geocoder API Release Notes 9► Release Major Changes
Element Description
Distance Distance in meters between the input coordinate
and the boundary of the area. If the area
covers the input coordinate the distance will be
negative.
MatchLevel landmark for landmark matches. Admin area
match levels as before (e.g. district).
Location.LocationId ID generated from source components. The
LocationID is not guaranteed to be permanent
across map versions.
Location.LocationType Currently the following types are supported:
area, address, trail, park, lake,
mountainPeak, volcano, river,
golfCourse, industrialComplex,
island, woodland, cemetery,
canalWaterChannel, bayHarbor,
airport, hospital, sportsComplex,
shoppingCentre, universityCollege,
nativeAmericanReservation,
railroad, militaryBase, parkingLot,
parkingGarage, animalPark, beach
Location.Name For areas of MatchLevel landmark this is the
area name. For example, "Palace of Fine Arts" For
admin areas no name element is provided.
Location.DisplayPosition Center point of the area.
Location.MapView Bounding box covering entire area.
Location.Address Address of the landmark POI if available. Lowest
admin hierarchy covering the entire landmark if
no POI is available.
Examples
Geocoder API Release Notes 10► Release Major Changes
Retrieve Area and Landmark Information at a PositionThe example below retrieves area and landmark information from a point close to the Presido in San
Francisco. It uses mode=retrieveAll. No radius is provided because we just want to know what is
at that point. For example, we are not interested in streets or addresses near-by.
reversegeocode.xml?mode=retrieveAll&prox=37.80358,-122.44832&gen=5
Two areas are intersecting with the given point: The landmark "Palace of Fine Arts" and the district
"Presidio". Below are details for both results. The complete admin and address information is also
part of the results. The information is just omitted below for space reasons. The distance is negative
for the landmark because the given point is inside the polygon.
Note: For the district result the distance is currently calculated from the given point to the
area centroid. This means it is always positive and there is no way to tell whether the given
point is actually inside the polygon or not. The plan is to change this with one of the next
releases: With gen=6 the distance for admin area results will also be calculated from the given
point to the polygon boundary.
distance: -73.7matchLevel: "landmark",...location: { locationId: "CARTO_31467673", locationType: "park", name: "Palace of Fine Arts", ... address: { label: "Palace Dr, San Francisco, CA 94123, United States", ...
distance: 1734.2matchLevel: "district",...location: { locationId: "AREA_5650784_S", locationType: "area", ... address: { label: "Presidio, San Francisco, CA, United States", ...
Geocoder API Release Notes 11► Release Major Changes
Retrieve Landmarks around a PositionThe second example looks at landmarks in the proximity of Sand Hill Rd in Palo Alto. For this example
we are not interested in admin information and also not in streets or addresses. The example
therefore uses mode=retrieveLandmarks and sets the radius to 1000 meters.
reversegeocode.xml?mode=retrieveLandmarks&prox=37.43823,-122.17796,1000&gen=5
There are five landmarks found within this proximity including a shopping center, a university, a
hospital and two parks. The matchLevel for all is "landmark". Here are details from one result:
distance: 171.7matchLevel: "landmark",...location: { locationId: "CARTO_1405659824", locationType: "hospital", name: "Stanford Hospital & Clinics", ... address: { label: "300 Pasteur Dr, Stanford, CA 94305, United States", ...
Geocoder API Release Notes 12► Release Major Changes
Suppression of Unnamed LinksThe map has many road links without names. For example, parks often have smaller roads or
trails that are unnamed. It makes sense to render those links on the map but these links are not
meaningful in all reverse geocoding use cases. Client applications can now suppress the retrieval of
unnamed links.
Usage: Request
Set the new additional data parameter SuppressStreetType to Unnamed.
Example:
reversegeocode.xml?mode=retrieveAddresses&prox=47.64551,-122.3361,200&additionaldata=SuppressStreetType,Unnamed
SuppressStreetType is a new parameter introduced with D44. Unnamed is currently the only
supported value.
This features also works with multi-reversegeocode endpoint since this endpoint forwards the
complete list of URL parameters to the reversegeocode endpoint.
Usage: Impact
Geocoder API Release Notes 13► Release Major Changes
The image on the left shows the results without suppression of unnamed links. The 10 closest links to
the set point are all in the park. None of them have a name. The image on the right shows the results
with suppression of unnamed links.
Default behavior additionaldata=
SuppressStreetType,Unnamed
Aggregation of Road Link Matches (gen=5)The Reverse Geocoder tries to aggregate links to a single street match instead providing one street
match per link where only coordinates are different. The additional matches are usually not adding
information for client applications.
Usage: Request
Client applications get this behavior change with gen=5.
Example: reversegeocode.xml?mode=retrieveAddresses&prox=37.4341,-122.2932,500&gen=5
Usage: Impact
The image on the left shows the results with gen<5. It shows many matches to links on the same
street. The image on right shows only two matches. One address match (D1) and one street level
match (2).
gen<5 gen=5
Geocoder API Release Notes 14► Release Major Changes
Complete List of API GenerationsTo enable backwards incompatible functionality within the same major version of an API without
impacting existing applications use the gen parameter. These API changes might cause conflicts with
existing client applications and are therefore tagged with a specific generation number. Below is the
complete list of generations. D44 introduces gen=5.
The gen parameter enables or disables backward incompatible behavior in the API.
• gen=0 default behavior
• gen=1
◦ If a reverse geocoding request for an address does not find an address or street within
the set radius the area information is returned instead. If gen=0 the results with a 10,000
meter radius are returned.
◦ Result MatchLevel for intersection matches is intersection. With gen=0 the
MatchLevel for intersection matches is street.
• gen=2
◦ Includes gen=1 functionality.
◦ Return the area display point (e.g. the centroid of the area) for reverse geocode area
responses. With gen<2 the DisplayPoint simply mirrors the point from the request.
◦ Return map version in element MapReference if requested via
locationattributes=(one of mr, mapReference, all)
• gen=3
Geocoder API Release Notes 15► Release Major Changes
◦ Includes gen=2 functionality.
◦ Reverse geocoding address results have display and navigation positions. With gen<3
address results from reverse geocoding only have a display position which in actuality is the
navigation position. With gen=3 this bug is fixed.
◦ MatchType pointAddress for reverse geocoding Point Address results. Otherwise
interpolated. With gen<3 address results from reverse geocoding always have
MatchType interpolated.
• gen=4
◦ Includes gen=3 functionality.
◦ Forward geocoding: Avoid ambiguous street level results that are near to each other and/
or can only be disambiguated based on one or a combination of district name/postal code.
With gen<4 forward geocoding responses have one result per postal code or district.
• gen=5 (recommended)
◦ Includes gen=4 functionality.
◦ Reverse geocoding: Enforce country filter. Reverse geocoder results are constrained to
the set country. This is a bug fix. With gen<5 reverse geocoder ignores the country filter.
Forward geocoder behavior does not change. The country filter has always been enforced.
◦ Reverse geocoding: Reverse Geocoder tries to aggregate links to a single street match
instead providing one street match per link where only coordinates are different.
◦ LocationType (element of Location) is specific to the result and not just point for any
result. LocationType is
▪ address: for MatchLevel houseNumber, street, intersection
▪ area: for MatchLevel country, state, county, city, district,
postalCode
▪ specific to the landmark for MatchLevel landmark. E.g. park, river,
golfCourse, industrialComplex, island etc.
This change impacts forward and reverse geocoder results.
Map Data VersionMap version for World remains at 2014Q1
Geocoder API Release Notes 16► Release Major Changes
China, Hong Kong, Macau update to 2013Q3
Geocoder API Release Notes 17► D44 Issues
Chapter
3
D44 IssuesTopics:
• Resolved Issues and Enhancements
• Known Issues
This section lists resolved issues and enhancements in the current
release. It also lists known issues in the current release.
Geocoder API Release Notes 18► D44 Issues
Resolved Issues and EnhancementsThe following table contains resolved issues. The list below summarizes the major resolved issues
relevant for a broad audience.
# Description
1 Turkey: Use of greater municipality names in address search
Geocoder defines metropolitan municipalities in Turkey (e.g. Istanbul,
Ankara, Izmir) now as city. This is the name that people commonly refer to
as city name. To have the admin structure consistent over whole Turkey
the provinces (il) are now defined as state and the province districts
(ilçe) as county. For the areas outside of metropolitan municipalities the
province district name is also being used as city name.
Example query: ESENKENT MAH. YÜCESOY SOK. NO.11, ÜMRANİYE,
İSTANBUL
Old Result:
label: Yücesoy Sokagi 11, 34776 Ümraniye, Turkey country: TURcounty: Istanbulcity: Ümraniyedistrict: Esenkentstreet: Yücesoy SokagihouseNumber: 11postalCode: 34776
New Result:
label: Yücesoy Sokagi 11, 34776 Istanbul, Turkeycountry: TURstate: Istanbulcounty: Ümraniyecity: Istanbuldistrict: Esenkentstreet: Yücesoy SokagihouseNumber: 11postalCode: 34776
Note: The response from Reverse Geocoder mode=retrieveAreas is
not aligned yet. It still shows the old admin levels. This will be resolved
with one of the next releases.
Geocoder API Release Notes 19► D44 Issues
# Description
2 Turkey: Improved matching of neighborhood names
For some cities in Turkey (e.g. Istanbul, Izmir) two types of neighborhoods
exist: officially recognized admin neighborhoods (mahalles) and non-
administrative neighborhoods. Both names are commonly used for
address and area search. Until now only the geocoder only recognized
the official admin name. Now also the unofficial names are recgnized and
matched. The address response always shows the official neighborhood
(mahalle) name.
Example:
Tahtakale is a neighborhood in the province district Fatih. Eminönü is also
a neigborhood of Fatih but it is not the offical admin. Both names are now
matched to district with 100%:
Tomruk Sok 5C, 34116 Tahtakale, Fatih, Istanbul
Tomruk Sok 5C, 34116 Eminönü, Fatih, Istanbul
District name in the response in both cases is Tahtakale (name of the
official neighborhood).
3 South Africa: Replacement of Metropolitan Municipality names with
commonly used city names
Match quality improvements and address rendering changes by replacing
the Metropolitan Municipality names with the real and commonly used city
names. These city names are taken from KA and KD zones. These are the
names that are commonly used for address search and that peopel are
expecting in the address label.
Example query: 26 Major Calvert St, Durban, 4052, South Africa
Old Result:
label: 26 Major Calvert St, Austerville, 4052, South Africa country: ZAFstate: Kwazulu Natalcounty: eThekwinicity: eThekwinidistrict: Austervillestreet: Major Calvert SthouseNumber: 26postalCode: 4052
Geocoder API Release Notes 20► D44 Issues
# Description
relevance: 0.82
New Result:
label: 26 Major Calvert St, Durban, 4052, South Africacountry: ZAFstate: Kwazulu Natalcounty: eThekwinicity: Durbandistrict: Austervillestreet: Major Calvert SthouseNumber: 26postalCode: 4052
relevance: 1
In the example above Durban was not matched at all in the old system.
This leads to the lower relevance. The result was only found with the
postal code. Such queries without postal code can even lead to empty
responses.
Queries with municipality name continue to work. For example, 221 SMITH
STREET, ETHEKWINI MUNICIPALITY, DURBAN, ZA
matches to the same location as before just that the response label is
different: 221 Smith St, Durban, 4001, South Africa.
City name is Durban and not Durban Central which is the district name.
4 Mexico: District "Centro" not matched because it is prefixed in map data
with city name but not in query
It is common for Mexico to include the district or neighborhood name
in address searches. It is also important for disambiguation since many
addresses exist multiple times within the same city. Centro is one of the
most popular districts. It exists in many cities. People refer to it simply as
"Centro" or "Col. Centro". (Col. stands for neighborhood (colonia)).
In the map data the city name is often prefixed with the name "Centro".
Example: Boca del Río Centro where Boca del Río is the city name. This
leads to low confidence, ambiguous, and often wrong matches.
Example query: Zamora No.7 Col. Centro, Boca del Rio, Veracruz, Mexico
Geocoder API Release Notes 21► D44 Issues
# Description
Old Result:
label: Centro 5, Petrolera, 94299 Boca del Río, VER, Méxicocountry: MEXstate: VERcity: Boca del Ríodistrict: Petrolerastreet: CentrohouseNumber: 5postalCode: 94299
relevance: 0.78matchQuality city: 1matchQuality district: 0
New Result:
label: Calle Zamora 7, Boca del Río Centro, 94290 Boca del Río, VER, Méxicocountry: MEXstate: VERcity: Boca del Ríodistrict: Boca del Río Centrostreet: Calle ZamorahouseNumber: 7postalCode: 94290
relevance: 1matchQuality city: 1matchQuality district: 1
5 Intersections not recognized with mixed case intersection indicator
("Esq")
Intersections are not recognized in queries when the intersection
indicator is provided in mixed case.
Example:
Calle 23 Esq Avenida 13, 10101 San José, Costa Rica
Result:
Avenida 13 66, 10102 San José, Costa Rica
matchLevel: houseNumber
Expected:
Calle 23 & Avenida 13, 10101 San José, Costa Rica
Geocoder API Release Notes 22► D44 Issues
# Description
matchLevel: intersection
Also fixed for "At" and "And". Related note: Searching for intersections
with character "y" as it is common in Mexico is not supported yet.
6 The MapVersion information in section MapReference for area results still
shows Q4/2013 instead of Q1/2014.
This is fixed. Area and address results show the same map version.
Known IssuesThe following table lists issues known to be present in the current release of the Geocoder API.
# Description
1 Taiwan Geocoding - Island Names are not able to be geocoded - Q2 2013 TWN Map
improvements
Islands to be considered as part of Taiwan.
2 Taiwan - Street Fallback - Returning the Best Candidate
If an address is not in the map then either a HSN fallback or up-hierarchy street level
match is expected. But in some cases the geocoder returns an address in the wrong
street or lane.
Example:
彰化縣彰化市介壽北路1號
House number 1 is not in the map data. The result is therefore a fallback to house
number 19:
No. 19, Jie Shou N. Rd., Changhua City, Changhua County 500, Taiwan
But if a house number fallback is not accepted (parameter:
additionaldata=HouseNumberMode,Streetlevel) then the result is expected to be a
street level match:
Jie Shou N. Rd., Changhua City, Changhua County 500, Taiwan
Geocoder API Release Notes 23► D44 Issues
# Description
The current response is an address match in a different – though close - street
(South instead of North) and in a Lane where no lane was requested:
No. 1, Lane 36, Jie Shou S. Rd., Changhua City, Changhua County 500, Taiwan
3 China: Reverse Geocoder retrieveAreas response not aligned with retrieveAddresses
The Reverse Geocoder retrieveAreas response is not aligned with the response from
retrieveAddresses and forward geocoder. City and district names are only available
in Chinese, the county information is wrong and state is empty (should be Chinese
provinces).
4 Labels for highway exits are missing the exit number
Only the highway name is contained in the label.
Workaround: Use highway name and exit number from the Name field.
5 Area IDs in geocoder and reverse geocoder results are not all admin PVIDs
Client appplications can request to include admin IDs in the result. These IDs are
supposed to be admin PVIDs that are used in RDF extraction as well.
In some cases the area IDs of geocoder and reverse geocoder results are not PVIDs
and they should therefore not be used by client applications as a reference:
- DistrictIDs for China results. These are IDs for hamlets which are encoded as POIs
and not as admins.
- CountryID for GBR. GBR is not a country admin in the map data. The geocoder
artificially creates it and assigns an ID.
The admin ID information is added to the result with parameter
locationattributes=all
Example:
Query:
&searchtext=London&locationattributes=all&gen=3
Result:
<MapReference> <MapVersion>Q1/2013</MapVersion> <CountryId>3458765896979120009</CountryId> <StateId>20248595</StateId> <CountyId>20337453</CountyId>
Geocoder API Release Notes 24► D44 Issues
# Description <CityId>20337454</CityId></MapReference>
Expected:
<MapReference> <MapVersion>Q2/2013</MapVersion> <StateId>20248595</StateId> <CountyId>20337453</CountyId> <CityId>20337454</CityId></MapReference>
6 The MapVersion information in section MapReference for results from China, Hong
Kong, and Macau is wrong. The current map version for these countries is Q3/2013.
Only for rest of World the map version is Q1/2014.
The map version information is added to the result with parameter
locationattributes=mr
Example:
Query:
&city=beijing&street=shang di qi jie&housenumber=7&locationAttributes=mr
Result:
<MapReference> ... <MapVersion>Q1/2014</MapVersion> ...</MapReference>
Expected:
<MapReference>... <MapVersion>Q3/2013</MapVersion>...</MapReference>
7 Reverse geocoder does not consider country parameter
Country parameter is defined as strict filter. No results from outside the set country
must be returned. The reverse geocoder does not consider the parameter.
For mode=retrieveAreas the result must be empty if the set prox is outside of the set
country.
Geocoder API Release Notes 25► D44 Issues
# Description
Example (prox set to location in Singapore, but country set to Malaysia):
reversegeocode.xml?
gen=4&country=MYL&mode=retrieveAreas&prox=1.41285,104.07732
Result:
Area Singapore
Expected:
empty response
For mode=retrieveAddresses the result must be an area fallback if no links or
addresses can be found within the set or default radius inside the set country.
Example (prox set to location in Singapore, country set to Singapore):
reversegeocode.xml?
gen=4&country=SGP&mode=retrieveAddresses&prox=1.41285,104.07732
Result:
Street matches in Malaysia
Expected:
Area fallback to Singapore
8 The navigation coordinate in the response for Hong Kong building name matches
is not always correct. It is the same as the display coordinate. Only when the query
matches to a house number in addition to the building name (MatchQuality element
houseNumber exists in result) the navigation coordinate is correct.
Example:
The queries
Shek Wu Shui Baptist Chapel, Hong Kong
and
Shek Wu Shui Baptist Chapel, 33 Fu Hing St, Hong Kong
both match to the same address. But only for the latter query the navigation
coordinate is correct.
9 Admin shapes are not returned by Reverve Geocoder mode=retrieveAddresses
Geocoder API Release Notes 26► D44 Issues
# Description
Only with Forward Geocoder and Reverse Geocoder mode=retrieveAreas admin
shapes can be retrieved. This will be fixed with a future release.
Retrieval of postal code shapes
(additionaldata=IncludeShapeLevel,postalCode) is not affected. It
continues to work with mode=retrieveAddresses.