survos / mapillary

2.45.12 2026-10-31 13:06 UTC

Requires

• php: ^8.5
• symfony/http-client-contracts: ^3.6
• symfony/property-access: ^8.1
• symfony/property-info: ^8.1
• symfony/serializer: ^8.1

Requires (Dev)

• phpunit/phpunit: ^13.0
• symfony/http-client: ^8.1

MIT

Published on Packagist.org on 2026-10-31 13:07 UTC

README

Typed, read-only Mapillary API v4 image client. PHP 8.5+, Symfony components 8.1+. No kernel or environment-variable reads in the library.

composer require survos/mapillary symfony/http-client

use Survos\Mapillary\MapillaryClient;
use Survos\Mapillary\SerializerFactory;
use Survos\Mapillary\Request\BoundingBox;
use Survos\Mapillary\Request\ImageSearch;
use Symfony\Component\HttpClient\HttpClient;

$client = new MapillaryClient(HttpClient::create(), SerializerFactory::create(), $accessToken);
$page = $client->searchImages(new ImageSearch(
    bbox: new BoundingBox(19.035, 47.490, 19.065, 47.510),
    isPano: true,
    limit: 20,
));
foreach ($page->images as $image) {
    echo $image->sourceUrl(), "\n";
}

getImage($id) retrieves metadata; sequenceImageIds($sequence) returns ordered IDs. iterateImages(new ImageSearch(creatorUsername: 'username')) follows creator cursors. Bbox searches return one bounded sample; possiblyTruncated flags reaching the limit. Bbox area must be less than 0.01 square degrees; coverage-tile decoding for larger searches is outside this milestone.

Nested geometry and creator are typed. Optional image fields are nullable; missing required ID, capture time or panorama flag fail on schema mismatch. Image::rawData retains the original image object and unknown fields; it may contain signed CDN URLs, so avoid logging it. Use image IDs and source URLs for durable identity.

The standalone client adds no caching/retries: inject HttpClient decorators. The bundle configures bounded GET retries. No default cache avoids cross-account mixing and stale signed URLs. Exceptions preserve HTTP/API codes, trace ID and Retry-After; messages are sanitized and omit the underlying transport exception. Do not dump HTTP debug traces or client objects containing credentials.

See the supported contract. This is a compatible subset, not a complete SDK. Image byte downloads, uploads, OAuth, map features/detections, vector tiles are unsupported.

Respect per-image licensing, photographer credit, and Mapillary attribution. Public image reads use the access token; not the client secret.

Tests: composer install, then vendor/bin/phpunit (or use the mono root runner with -c lib/mapillary/phpunit.xml.dist). Tests run offline.

Nearby search: nearbyImages(new NearbySearch(47.507, 19.046, radius: 50, limit: 20)) returns at most 100 candidates within 50 meters, ranked by the server with panorama preference. The API does not document a panorama-only filter for radius requests. The command mapillary:images:nearby 47.507 19.046 --limit=20 filters the returned candidates locally to panoramas; --include-flat shows all. Neither radius nor bbox samples guarantee completeness.