Endpoint `/wp-json/pronamic-maps/v1/address/9203ka`

remcotolsma commented 3 years ago

Currently the REST API endpoint to retrieve address information by a postcode is: /wp-json/pronamic-maps/v1/address/9203ka

The https://geodata.nationaalgeoregister.nl/ API uses suggest in it's endpoint:

And Google uses geocode/json: https://maps.googleapis.com/maps/api/geocode/json?components=postal_code:9203KA|country:NL&sensor=false&key=

Both webservices can return multiple results, in our case we need an endpoint that returns the best match:

Is it smart to set up the endpoint purely for zip code input?

The https://www.postcodeapi.nu/ uses: https://api.postcodeapi.nu/widget/lookup

And https://www.postcode.nl/ uses: https://www.postcode.nl/json/international/v1/autocomplete/nld/9203%20KA%2039b/nl-NL

And https://github.com/api-postcode/php-client/blob/master/Client/PostcodeClient.php uses: https://json.api-postcode.nl/?postcode=9203%20KA&number=39

https://github.com/pronamic/wp-pronamic-maps/blob/main/includes/autopopulate-address.php#L135-L140

French postcode: 69006 (WP Rocket) → https://goo.gl/maps/TYBhVsekqm7GhfPB8

https://maps.googleapis.com/maps/api/geocode/json?components=postal_code:69006&sensor=false&key= → ZERO_RESULTS
https://maps.googleapis.com/maps/api/geocode/json?components=postal_code:69006|country:FR&sensor=false&key= → 1 item

To lookup a postcode we need to know the country (code). We can derive this from get_locale() (nl_NL) but that is not always reliable. We could also implement a setting/option for the default/base country (code). Just like WooCommerce:

Heeft elke postcode een unieke straat? Veelal heeft elke postcode een unieke staat, toch komt het voor dat sommige postcodes bij meerdere straten horen. Zie als voorbeeld: postcode 1097DN, onder deze postcode vallen Julianaplein en Wibautstraat in Amsterdam.

Source: https://postcodebijadres.nl/veelgestelde-vragen

Op bijvoorbeeld https://offerte.nl/boekhouder/offertes-aanvragen tonen ze gewoon Julianaplein, maar dat is in principe niet correct:

Also on https://offerte.nl/boekhouder/offertes-aanvragen they validate the postcode, the Dutch postcode 1000 AA is 'invalid': https://nl.wikipedia.org/wiki/Postcodes_in_Nederland

/wp-json/pronamic-maps/v1/lookup?country=NL&postcode=9203KA
/wp-json/pronamic-maps/v1/lookup?country=FR&postcode=69006

I think we should also autocomplete if there is 1 result, if there are multiple results, autocompletion doesn't make sense.

PronamicMapsAutocompleteFields( {
    country: document.getElementById( '' ),
    postcode: document.getElementById( 'input_3_3' ),
    address: document.getElementById( 'input_3_2' ),
    city: document.getElementById( 'input_3_4' )
} );

Should we also look at using https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/autocomplete or https://developer.mozilla.org/en-US/docs/Web/HTML/Element/datalist. In case of multiple results we could also attach a <datalist> element with available options to the input element.

Internal Basecamp to-do: https://basecamp.com/1810084/projects/16121870/todos/440283501

remcotolsma commented 3 years ago

@rvdsteege Do you have any ideas/feedback on this?

cc: @kjtolsma

rvdsteege commented 3 years ago

Discussed with @remcotolsma at office:

adding support for multiple address components via URL query parameters instead of only a postal code would be welcome (i.e. for the 1097DN postal code case, which consists of multiple street names);
endpoint could be /wp-json/pronamic-maps/v1/suggest or /wp-json/pronamic-maps/v1/suggest/address or /wp-json/pronamic-maps/v1/address/suggest, lookup is more appropriate if there is a known unique identifier for a location/address/etc. (which is not the case with autocomplete suggestions);
autocompleting a field indeed only makes sense if there is a single result, however a <datalist> can be used to let users choose from suggestions (or otherwise fill in their own desired field value);
Gravity Forms integration (#2) can use the autocomplete selectors from the field settings — in case of an address field, only fields within that address should be updated or if an address is constructed with other fields, an additional autocomplete selector (such as billing or shipping) could be used to "group" address fields for the address suggestions.

remcotolsma commented 3 years ago

REST API endpoint allow available if referer is the WordPress site?

https://pay.local/wp-json/pronamic-maps/v1/location/self

remcotolsma commented 3 years ago

By default https://geodata.nationaalgeoregister.nl/locatieserver/v3/suggest?q=9203ka returns 10 rows, there are 17 matches found. In the first 10 rows there is just 1 postcode type match, but can we assume that there is no postcode in the other 7 items? Or should we query specific for postcode matches → https://geodata.nationaalgeoregister.nl/locatieserver/v3/suggest?q=9203ka&fq=type:postcode?

https://github.com/PDOK/locatieserver/wiki/API-Locatieserver

remcotolsma commented 3 years ago

Owh 😍: https://geodata.nationaalgeoregister.nl/locatieserver/v3/free?q=9203ka&fq=type:postcode

pronamic / wp-pronamic-maps

Endpoint `/wp-json/pronamic-maps/v1/address/9203ka` #1