Download the PHP package automapa/map-services without Composer

Automapa Map Services PHP SDK

European Geocoding, Routing & Address Autocomplete

PHP SDK for the Automapa Map Services REST API. Simplifies integration with geocoding, routing, and address autocomplete services for Europe.

Getting started with your .env file

You will receive a .env file from us containing your API credentials. Place it in the root directory of this repository:

Once the .env file is in place, you can test all endpoints against the live API using Docker — no local PHP installation required:

Zero dependencies. The SDK has no runtime Composer dependencies — only ext-curl and ext-json, which are bundled with every standard PHP installation. It is compatible with PHP 8.0 and above.

1. Overview

The SDK covers:

• Geocoding — convert an address to coordinates and back
• Routing — calculate routes, distance matrices, and point-order optimization
• Address autocomplete — suggestions as the user types
• Google Geocoding API compatibility — optional google response format

For the full list of endpoints and parameters, see the Automapa REST API documentation.

2. Installation

Requirements: PHP 8.0+, ext-curl, ext-json.

3. Client configuration

4. Session handling

A session is opened automatically (lazy) on the first call that requires authorisation. To open it manually:

5. Available services

Geocoder

geocode() — address to coordinates

geocodemulti() — batch geocoding (up to 100 addresses)

revgeocode() — coordinates to address

revgeocodemulti() — batch reverse geocoding

Autocomplete

Address and POI autocomplete — returns suggestions as the user types.

search() — search by phrase

Each items entry contains: type, subtype, name, province, district, community, place, quarter, street, number, postal_code, coords.{x,y}.

searchAddress() — step-by-step address search

Useful for multi-field address forms (city → street → number → postcode).

Each entry may contain: city, street, number, zipcode, count, and optionally coords.{x,y}.

Note on Autocomplete coordinates: Unlike Geocoder, coordinates are nested: coords.x = longitude, coords.y = latitude.

Routes

Route calculation, distance matrix, and point-order optimisation.

route() — calculate a route

matrix() — distance / time matrix

optimize() — synchronous optimisation (max 10 points)

optimizeQueue() + optimizeQueueResult() — asynchronous optimisation (max 50 points)

Road

Query road segment metadata and speed limits. Each method accepts an optional $extra array for any additional API fields; named parameters take priority.

RoadPermit

Manage road permits (weight/size restrictions) tied to a geographic polygon. Each method accepts an optional $extra array for any additional API fields not listed in the signature.

Available permissions keys: tr_tonnage (total weight, t), tr_tonn_axis (axle load, t), tr_height (m).

Speed

GPS-trace speed-violation analysis — submit a trace asynchronously and poll for results.

speedReport() — submit a GPS trace

speedReportResult() — poll for the analysis result

Each overspeedingArray entry contains: duration (s), length (m), type (category 1–6), speedMax, speedAvg (km/h), speedLimit (km/h), urbanArea, startLocation, startPoint.{x,y}, endLocation, endPoint.{x,y}, startTime, endTime (Unix timestamps).

The optional limit parameter (default 1) sets the minimum violation category to include (1–6).

6. Examples

or simply run make examples to run all examples.

7. Passing additional parameters

The SDK does not restrict unknown parameters — all fields are forwarded to the API as-is. Every endpoint accepts an $extra array as its last argument. Named params always take priority over $extra:

8. Low-level call() and request()

9. Response formats: native vs google

10. Google format field limitations

Note: The Automapa API uses x = longitude and y = latitude — the opposite of Google's convention.

11. Error handling

License

MIT © 2026 Automapa sp. z o.o.