2.0.0
Explorer
Developer Support
Mapillary Upload Flow
Setup
The Mapillary API lets you interact with Mapillary on the behalf of a user. This is achieved by using OAuth 2.0.
You must set the following:
- Callback URL:
APP URL - Allow this application to:
user:email,user:read,user:write,public:write,public:upload
All other settings can be configured as you like.
Once you click save, the app will be assigned a client id and client secret. Add these to the .
env file, along with the callback URL you just set. Here is a sample:1
MAPILLARY_APP_ID=ABCDEFGHIJK123
2
MAPILLARY_SECRET=ZYX987654321
3
MAPILLARY_REDIRECT_URI=https://MTPW_DOMAIN/accounts/check-mtpu-gsv-oauth
Copied!
Workflow
0. Overview
%20V1.jpg?alt=media&token=8085cf97-a152-457e-9f51-a1797cda8aa9)
1. User publishes sequence
2. User authenticates to Mapillary
We should request explicit permissions on each upload when user initiates Mapillary upload.
When a user tries to upload images to Mapillary, they will grant the Google Mapillary app access to act on their behalf (see setup).
3. Create an upload session on Mapillary
4. Upload the imagery to the upload session on Mapillary
5. Publish the upload session on Mapillary (by closing the upload session)
At this point sequence enters Mapillary Published state Processing
6. Check for upload session for errors
Once an upload session gets published, you will not be able to find this session any more as it's moved for processing, unless it fails as a failed session.
This endpoint will only return failed sessions. If the sequence has not encountered any errors during the publishing workflow, you will not see it listed here.
If a failed upload session occurs, user will see a failed message and Mapillary integration will be enter Mapillary error state allowing user to retry upload.
7. Get Mapillary Sequence ID
Unfortunately Mapillary does not provide the Sequence_Key for an upload session in a response (because sequence id only generate by Mapillary when processing complete).
Therefore we need to do a bit of filtering with the Mapillary Sequences endpoint to get this info:
7.1. Get upload user
After the user obtains the oAuth token (we have this following authorisation to upload), the app makes an API call to
https://a.mapillary.com/v3/me with the users token to get the caller's user_key.The
user_key is then stored in app against the Sequence (note, user might have multiple Mapillary accounts, so this should not be stored at user level)7.2. Request user sequences
It is not possible to query the Mapillary API Search Sequence endpoint to find the Sequence Key of the Sequence uploaded:
user_key: obtained in step onestart_time: time of first photo in UTC uploaded in sequence (MAPCaptureTime)end_time: time of last photo in UTC uploaded in sequence (MAPCaptureTime)
We can now form a request:
1
curl "https://a.mapillary.com/v3/sequences?userkeys=USER_KEY&start_time=TIME&end_time=TIMEclient_id=<YOUR_CLIENT_ID>"
Copied!
It can take up to 72 hours for a Sequences to be published, and thus a response to appear from this request.
If the app makes a query to this endpoint and an empty response is returned, the app keeps the sequence in Mapillary unpublished state.
When in this unpublished state, this step (check for upload session errors) is triggered every 5 minutes whilst app is open and app remains in Mapillary Processing state
When a sequence is published it will return a response like:
1
{
2
"type": "FeatureCollection",
3
"features": [
4
{
5
"type": "Feature",
6
"properties": {
7
"camera_make": "Apple",
8
"captured_at": "2016-03-14T13:44:53.860Z",
9
"coordinateProperties": {
10
"cas": [
11
323.032,
12
320.892,
13
333.622,
14
329.948
15
],
16
"image_keys": [
17
"LwrHXqFRN_pszCopTKHF_Q",
18
"Aufjv2hdCKwg9LySWWVSwg",
19
"QEVZ1tp-PmrwtqhSwdW9fQ",
20
"G_SIwxNcioYeutZuA8Rurw"
21
]
22
},
23
"created_at": "2016-03-17T10:47:53.106Z",
24
"key": "LMlIPUNhaj24h_q9v4ArNw",
25
"pano": false,
26
"user_key": "AGfe-07BEJX0-kxpu9J3rA",
27
"username": "pierregeo"
28
},
29
"geometry": {
30
"type": "LineString",
31
"coordinates": [
32
[
33
16.432958,
34
7.246497
35
],
36
[
37
16.432955,
38
7.246567
39
],
40
[
41
16.432971,
42
7.248372
43
],
44
[
45
16.432976,
46
7.249027
47
]
48
]
49
}
50
}
51
]
52
}
Copied!
Where
features.key is the value of the Sequence Key we need to store and features.image_keys are the image ids we need to store.Design decision: theoretically it is possible a user has two sequences in different places with start and end times in the specified range. However, it was decided because such a scenario is VERY unlikely, we accepted the risk of such collisions.
8. Mapillary published state
When sequence and image IDs from Mapillary stored, the sequence enters Mapillary Published state and the sequence is now Published.
​
Appendix: Mapillary Sequence states
​
id
Sequence State
Description
mapillary-state-1
Mapillary upload processing
When user published sequence they need to authenticate to Mapillary. Once authentication to Mapillary is successful and upload begins (successfully) then sequence enters this state. If any authentication failure before first upload, sequence remains in earlier unpublished state.
mapillary-state-2
Mapillary upload complete
When all files have been uploaded to Mapillary sequence enters this state. Note, sequence does not immediately publish to Mapillary.
smapillary-state-3
Mapillary upload published
After some time, about 48 hours, the Sequence is published by Mapillary (unless failures). We need to query Mapillary to check publish status periodically. When a published state is returned, sequence enters this state. At this point a user is free to publish to other integrations.
mapillary-state-4
Mapillary error
Sometimes Mapillary might report an error when they process the images. We need to query Mapillary to check publish status periodically. When an error state is returned, sequence enters this state.
Last modified 3mo ago
Copy link