[Requirements] 2. Get Image Close To

[Rubix982]

Is your feature request related to a problem? Please describe.
This issue deals with the 2nd requirement from the PRD over outputting getting "near image".

Describe the solution you'd like
NA

Describe alternatives you've considered
This feature has the following implementation needs,

1. A function taking a longitude, latitude as argument and outputting near the image
2. Options for fields to include with an “all” option or individual list. For the list of fields that can be sent to the API, check out https://blog.mapillary.com/update/2021/06/23/getting-started-with-the-new-mapillary-api-v4.html
3. Option for radius, default being within 200 meters or less.
4. Option for pano, flat, or both
5. Possible options: date filter, org key
6. Geometry is always a field included, this is NOT a parameter, but an option sent to the API when a request is made, check out https://blog.mapillary.com/update/2021/06/23/getting-started-with-the-new-mapillary-api-v4.html for more details

Additional context
This makes an API call with the token set in R01 and returns a JSON object. It may make sense to set an option for the response format to be GeoJSON which slightly reshuffles the data format.

Reference:

• Converting datetime.date to UTC timestamp in Python

[Rubix982]

@cbeddow for the 5th option, 'date filter', what is the date format that the API accepts? I can't find date related filtering option on the APIv4 documentation, https://www.mapillary.com/developer/api-documentation/. Thanks!

[cbeddow]

@Rubix982 the tiles will accept a filter based on Unix epoch milliseconds. https://www.unixtutorial.org/epoch-time/

So in the tiles, after requesting them we need to manually do maybe a filter like:

min_date = 1547318486
filtered_features = [feature for feature in geojson_feature_collection["features"] where feature["properties"]["captured_at"] >= min_date]

The user might set a min_date and a max_date, or just one of those.

My concern is that the unix epoch time is not user-friendly as an input. Most users on Mapillary search by date for filters, not often hours/minutes.

I think we should have the input be in YYYY-MM-DD format (ISO 8601) as a standard: https://www.iso.org/iso-8601-date-and-time-format.html

Example:

get_data(min_date=2020-09-01,max_date=2021-06-01)

^ something like this. Or maybe the date range is a list, so we do:

get_data(daterange=[2020-09-01,2020-06-01])

And always require a min and max, or allow a wildcard type character like:

get_data(daterange=[2020-09-01,*])

Not sure if * is correct to use with a python function like this though.

Then if they want to be specific to hours and minutes, it is accepted to not just put YYYY-MM-DD but also to extend to YYY-MM-DDTHH:MM:SS. For example:

2020-09-15T15:53:00

So we can read and accept both, but no partial format in between such as YYYY-MM-DDTHH, it must have MM:SS on the end, or have only YYYY-MM-DD if there is not a full THH:MM:SS.

Then we convert that to epoch milliseconds and run a filter.

How does that sound?

[Rubix982]

Seems perfect and concise. Makes a lot of sense from the user's end.

[Rubix982]

@cbeddow, for this part,

And always require a min and max, or allow a wildcard type character like:

get_data(daterange=[2020-09-01,*])

Not sure if * is correct to use with a python function like this though.

Does the * mean today's date?

[cbeddow]

@Rubix982 yes that makes sense, if unspecified means today. If the first argument is * or some wild card, then it should be epoch time of 0

[Rubix982]

@cbeddow The filtering we want to be available for this requirement needs to be joined via the id parameter ( the image_id ). For this, I have had to utilize three endpoints,

'https://tiles.mapillary.com/maps/vtp/mly_map_feature_point/2/{z}/{x}/{y}?access_token=XXX' # for id, value, first_seen_at, last_seen_at
'https://graph.mapillary.com/:image_id' # for fields, such as geometry and 'all' as mentioned above
'https://tiles.mapillary.com/maps/vtp/mly1_public/2/{z}/{x}/{y}?access_token=XXX' # For the organization_id to filter via organization key, and is_pano attribute for pano, flat or both

The problem primarily is with the 2nd endpoint, passing any other field other than geometry causes the API to fail. The error I get is similar to this,

{
   "error": {
      "message": "Tried accessing nonexisting field (altitude) on node type (ChunkObject)",
      "type": "MLYApiException",
      "code": 100,
      "fbtrace_id": "A514B-_ujHi2raqz20DgoGT"
   }
}

For now, I'll open up an issue to keep a track of this and reduce the default parameter from all to geometry, which converts our base endpoint from and to the following form,

# From
'https://graph.mapillary.com/219262519730517/?fields=altitude,atomic_scale,camera_parameters,camera_type,captured_at,compass_angle,computed_altitude,computed_compass_angle,computed_geometry,computed_rotation,exif_orientation,geometry,height,thumb_256_url,thumb_1024_url,thumb_2048_url,merge_cc,mesh,quality_score,sequence,sfm_cluster,width&access_token=MLY|XXX

# To
'https://graph.mapillary.com/219262519730517/?fields=geometry&access_token=MLY|XXX

[cbeddow]

@Rubix982 so the mly_map_feature_point should not be used in this. It should only call the mly1_public endpoint images layer, and retrieve the images within a radius of the input coordinates (lon,lat).

It may be confusing that I was saying "point" which can mean a longitude,latitude, but also a map feature point which is anon-image, non-traffic sign piece of data such as a bench, crosswalk, street lamp or utility pole. But that should be the data the user is retrieving here. Let's review the code on this Thursday too.