Maps2 API 

getFirstFoundPositionByAddress 

Give it an address (string) as first argument and you will get first found address as Position object. If the geocoding service has nothing found or an error occurs this method will return null. There is no need to :php:rawurlencode the address as we will do it for you.

getPositionsByAddress 

Give it an address (string) as first argument and you will get all found results from geocoding service as Position object in an ObjectStorage.

getGeoCodeResult 

Same as getPositionsByAddress, but returns a GeoCodeResult value object containing the found positions or the error, why the address could not be geocoded. Use it, if you want to show a meaningful message to your users.

$result->error->type is a case of the provider independent enum \JWeiland\Maps2\Client\ClientErrorEnum:

NO_POSITIONS_FOUND

The map provider did not find the address. Ask the user to check the input.

REQUEST_DENIED

The map provider rejected the request, e.g. because of an invalid API key or because the API key is restricted to other IP addresses.

QUOTA_EXCEEDED

The request limit or the quota of the map provider was exceeded.

INVALID_REQUEST

The map provider did not accept the request.

INVALID_RESPONSE

The response of the map provider is not valid JSON.

SERVICE_ERROR

The map provider could not be reached or answered with an unknown error.

Only NO_POSITIONS_FOUND is caused by the user input. $result->error->message contains the technical message of the map provider. Please don't show it to frontend users, as it may contain sensitive data like the IP address of your server.

$result = $this->geoCodeService->getGeoCodeResult($address);
$position = $result->getFirstPosition();
if ($position === null) {
    $message = match ($result->error?->type) {
        ClientErrorEnum::NO_POSITIONS_FOUND => 'Please check your address',
        default => 'Address lookup is currently not possible',
    };
}

createNewPoiCollection 

Use it, if you have some location records in your extension and want to create a new PoiCollection relation automatically while saving your location record.

assignPoiCollectionToForeignRecord 

We have over 5 extensions working together with maps2 and we always have to implement a part to save the PoiCollection UID to our other extensions. Wouldn't it be better to have a centralized method doing that?

addForeignRecordsToPoiCollection 

This method is NOT public API. It will be called automatically, if you call getForeignRecords of a PoiCollection. It contains a SignalSlot where you can remove or modify foreignRecords before adding them to PoiCollection.

// create new map-record and set it in relation
$position = $this->googleMapsService->getFirstFoundPositionByAddress($this->getAddress($eventLocation));
if ($position instanceof Position) {
    $tsConfig = $this->getTsConfig($eventLocation);
    $this->googleMapsService->assignPoiCollectionToForeignRecord(
        $this->googleMapsService->createNewPoiCollection(
            (int)$tsConfig['pid'],
            $position,
            array(
                'title' => $eventLocation['location']
            )
        ),
        $eventLocation,
        'tx_events2_domain_model_location',
        'tx_maps2_uid'
    );
}

getColumnRegistry 

Get the Maps2 registry as ColumnRegistrationStorage object for all tables, columns and its configuration.

We have added a service maps2.columnRegistry to Services.yaml which you can use for your extensions:

MyVendor\MyExtension\Service\MyService:
  arguments:
    $columnRegistry: '@maps2.columnRegistry'