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.


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.


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


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", ...


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", ...


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


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


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



◦ 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


◦ 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)


◦ 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


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.


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.


# 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


# 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


# 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


# 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


# 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>


# 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.


# 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


# 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.

geocoder apidocumentation.developer.here.com/pdf/geocoding_nlp/6.2.53... · 2019-07-10 · reverse...

Documents