OpenStreetCam API Reference
OpenStreetCam is a free and open platform for street level imagery. Anyone can contribute images with a smartphone and our open source apps. OSV will detect salient features from the uploaded images such as signs, lanes and road curvature to improve OpenStreetMap.
API Endpoint
http://openstreetcam.org/Terms and Conditions of Use http://openstreetcam.com/terms/
Schemes: http
Version: 1.0.0
How it works
How to display
Uploaded sequences are aggregated and matched to OSM road network. To display where OSV has coverage, the backend can provide a list of polylines in a specified bounding box. Then you can ask for all sequences or photos from a specific location ( eg. on click ) to get to the images.
Get the segments within a bounding box.
The requests could be paginated by specifying the page and items per page(ipp). The result will be a list of segments and their geometry(an ordered list of positions).
Nearby sequences
The request returns the nearby sequences of a specified location and a radius distance.
Get nearby photos.
The request returns the nearby photos of a specified location. The request could be filtered by OSM user ID, creation date, wayId and radius. The photos can be displayed on the map by using photo's location.
How to upload
You can upload two types of files on the OSV backend:
- Recordings from the OSV apps. They are compressed in video files and have a metadata file for each track.
- Geotagged photos from different sources.
Creating the sequence
Before starting the upload, create a sequence by generating a new ID. If the data comes from the OSV apps, the metadata has to be uploaded with this request. Once the sequence has been created, you can upload files to the sequence.
Uploading a video file
This requests add a video file to a specific sequence. Use the sequenceIndex parameter to set the index of the current video in the sequence.
Uploading a photo
In order to upload a photo you have to specify the GPS coordinate and the GPS accuracy when the picture was taken.
Finish the sequence
Notify the server, that all files in a sequence were uploaded. The server will start processing the uploaded data. The processing workflow implies: (optionally) split of video into photos, getting data from metadata file, mapping the track's path to the map's segments and blurring.
Authentication
For each secured method you have to use the access_token parameter. In order to get the access_token, you have to get the request_token and secret token returned after OAuth authentification on OSM.
OpenStreetCam authentication
OpenStreetCam authentication uses request_token and secret_token obtained after OAuth authentication on OSM.
The request has been processed without incidents
An unexpected server error has occurred
Response Example (200 OK)
{
"osv": {
"$ref": "#/definitions/Auth"
},
"status": {
"$ref": "#/definitions/Status"
}
}
Sequence
Sequence methods provide access to information and operations related to OSV sequences. A sequence is composed by multiple photos, recorded during one trip. Each sequence taken with the OSV apps has a metadata file associated. Metadata file contains information like: photo timestamp, photo position(lat, long), elevation, GPS speed, OBD2 speed, sensors information, etc. After creating the sequence and uploading the video, all the data is processed, so the sequence has several processing statuses: NEW: Sequence data isn't processed yet. VIDEO_SPLIT: the uploaded video is spliting. UPLOAD_FINISHED: the video upload is finished. PROCESSING_FINISHED: data processing is finished. PROCESSING_FAILED: data processing failed.
Get Sequence details
Get Sequence details.
The request has been processed without incidents
An unexpected server error has occurred
Response Example (200 OK)
{
"osv": {
"$ref": "#/definitions/SequenceV3"
},
"status": {
"$ref": "#/definitions/Status"
}
}
Create sequence
On sequence creation, the metadata file is required.
The request has been processed without incidents
An unexpected server error has occurred
Response Example (200 OK)
{
"osv": {
"$ref": "#/definitions/SequenceV4"
},
"status": {
"$ref": "#/definitions/Status"
}
}
Get sequence's photo list
Each sequence has a collection of photos ordered by sequenceIndex.
The request has been processed without incidents
An unexpected server error has occurred
Response Example (200 OK)
{
"osv": {
"$ref": "#/definitions/Osv"
},
"status": {
"$ref": "#/definitions/Status"
}
}
Remove Sequence
Remove the sequence by specifying its ID. The sequence and all its data will be removed.
The request has been processed without incidents
An unexpected server error has occurred
Response Example (200 OK)
{
"status": {
"$ref": "#/definitions/Status"
}
}
Notify the server that the uploading has been finished
After uploading the video, the server should be notified that the uploading is finished. So the sequence processing status is changed from NEW to UPLOAD_FINISHED.
The request has been processed without incidents
An unexpected server error has occurred
Response Example (200 OK)
{
"osv": {
"$ref": "#/definitions/OsvV2"
},
"status": {
"$ref": "#/definitions/Status"
}
}
List of sequences
Get the list of sequences.
The request has been processed without incidents
An unexpected server error has occurred
Response Example (200 OK)
{
"currentPageItems": "array",
"status": {
"$ref": "#/definitions/Status"
},
"totalFilteredItems": "array",
"tracksStatus": {
"$ref": "#/definitions/TracksStatus"
}
}
Photo
Photo methods provide access to information and operations relating to the photos. Photos are stored ordered by sequenceIndex. For each photo, is generated a thumbnail and a large thumbnail. After video spliting, all photos are processed. There are several processing statuses: NEW: Photo isn't processed yet. PROCESSING: Photo is processing. FINISHED: photo processing is running.
Upload Photo
Upload the sequence's photo.
The request has been processed without incidents
An unexpected server error has occurred
Response Example (200 OK)
{
"status": {
"$ref": "#/definitions/Status"
}
}
Remove Photo
Remove a photo by specifying photo ID.
The request has been processed without incidents
An unexpected server error has occurred
Response Example (200 OK)
{
"status": {
"$ref": "#/definitions/Status"
}
}
Video
Video methods provide access to information and operations relating to the videos. All the sequence's photos are recorded into a video. The video is uploaded to the server, splited into photos, and processed. During processing time, the video has several processing statuses: NEW: video isn't processed yet. SPLIT_FINISH: video split is finished.
Upload video to specific sequence
The video contains all the recorded sequences'photos. After being uploaded to the server, the video is splited into photos, and then processed. During the video processing, the video has the following processing statuses: NEW: the video isn't uploaded yet. SPLIT_FINISHED: the video split is finished.
The request has been processed without incidents
An unexpected server error has occurred
Response Example (200 OK)
{
"osv": {
"$ref": "#/definitions/OsvV6"
},
"status": {
"$ref": "#/definitions/Status"
}
}
Map
Map methods provide access to information and operations relating to the map. All the uploaded sequences are maped to the map's segments. So each map's segement belongs to one or multiple sequences.
Nearby sequences
Get list of nearby sequences, in radius of specified distance and location.
The request has been processed without incidents
An unexpected server error has occurred
Response Example (200 OK)
{
"osv": {
"$ref": "#/definitions/Nearby"
},
"status": {
"$ref": "#/definitions/Status"
}
}
Get Nearby Photos
Returns the nearby photos of a specified location and radius distance.
The request has been processed without incidents
An unexpected server error has occurred
Response Example (200 OK)
{
"currentPageItems": "array",
"status": {
"$ref": "#/definitions/Status"
},
"totalFilteredItems": "array",
"tracksStatus": {
"$ref": "#/definitions/TracksStatus"
}
}
Matched tracks
All sequences are maped to the map's segments. This method is used to display all the matched segments on the map. Each segment is represented by its geometry(a list of geolocations).
The request has been processed without incidents
An unexpected server error has occurred
Response Example (200 OK)
{
"currentPageItems": "array",
"removeTracks": "array",
"status": {
"$ref": "#/definitions/Status"
},
"totalFilteredItems": "array"
}
User
Get user details
The user details represent statuses and activity information of the user, like overall rank, the covered total distance, total number of photos etc.
The request has been processed without incidents
An unexpected server error has occurred
Response Example (200 OK)
{
"osv": {
"$ref": "#/definitions/OsvV7"
},
"status": {
"$ref": "#/definitions/Status"
}
}
Models
CreateSequenceResponse: object
- osv: SequenceV4
- status: Status
DetailsResponse: object
- osv: SequenceV3
- status: Status
MyListResponse: object
- currentPageItems: object
- totalFilteredItems: object
- status: Status
- tracksStatus: TracksStatus
Nearby: object
- lat: number
-
Latitude of the nearest matched point on the map.
- lng: number
-
Longitutde of the nearest matched point on the map.
- from: integer (int32)
-
From Node ID.
- to: integer (int32)
-
To Node ID.
- way_id: integer (int32)
-
Way ID.
- sequences: object[]
-
List of nearby sequences.
NearbyPhotosResponse: object
- currentPageItems: object
- totalFilteredItems: object
- status: Status
- tracksStatus: TracksStatus
OsvV6: object
- video: Video
OsvV7: object
- obdDistance: number
-
OBD Distance.
- overallRank: integer (int32)
-
Overall Rank.
- totalDistance: number
-
Total distance.
- totalPhotos: integer (int32)
-
Total Photos.
- totalTracks: integer (int32)
-
Total Sequences.
- username: string
-
Username.
- weeklyRank: integer (int32)
-
Weekly Rank.
Photo: object
- date_added: string
-
Date the photo has been added.(yyyy-mm-dd (H:i)) format.
- gps_accuracy: number
-
GPS accuracy.
- user: string
-
User name.
- heading: number
-
The photo's position heading.
- id: integer (int32)
-
Photo ID.
- lat: number
-
Latitude of photo's location.
- lng: number
-
Longitutde of photo's location.
- lth_name: string
-
The URL of large thumbnail.
- match_lat: number
-
Matched latitude of photo's location.
- match_lng: string
-
Matched longitude of photo's location.
- name: string
-
The URL of full sized photo.
- sequence_id: integer (int32)
-
Sequence ID.
- sequence_index: integer (int32)
-
The photo index.
- th_name: string
-
The URL of small thumbnail.
- way_id: integer (int32)
-
The Way ID.
SequenceV1: object
- address: string
-
Address where recording started.
- author: string
-
Owner of the sequence.
- date: string
-
Date the sequence has been added.(dd.mm.yyyy) format.
- distance: number
-
Distance of the siquence(KM).
- hour: string
-
Hour of added date. (hh AM|PM) format.
- lat: number
-
Latitude of the sequence starting point.
- lng: number
-
Longitutde of the sequence starting point.
- photo: string
-
The URL of sequence first photo
- photo_no: integer (int32)
-
Number of photos.
- sequence_id: integer (int32)
-
Sequence ID.
- sequence_index: integer (int32)
-
Sequence index.
SequenceV2: object
- location: string
-
Address where recording started.
- platform_name: string
-
Platform name.
- platform_version: string
-
Platform version.
- app_version: string
-
Application version.
- reviewed: string
-
Reviewd. Available values: (0,1).
- changes: string
-
Changes.
- recognitions: string
-
Number of recognitions.
- date_added: string
-
Date the sequence has been added.(yyyy-mm-dd (H:i)) format.
- distance: number
-
Distance of the siquence(KM).
- image_processing_status: string
-
Image processing status. ('NEW','VIDEO_SPLIT','UPLOAD_FINISHED','PROCESSING_FINISHED','PROCESSING_FAILED').
- current_lat: number
-
Latitude of the sequence starting point.
- current_lng: number
-
Longitutde of the sequence starting point.
- obd_info: string
-
OBD Info.
- meta_data_filename: string
-
The URL of metadata file.
- thumb_name: string
-
The URL of thumbnail.
- photo_no: integer (int32)
-
Number of photos.
- id: integer (int32)
-
Sequence ID.
- user_id: integer (int32)
-
User ID.
- country_code: string
-
Country Code.
- se_lat: number
-
Latitude of boundig box's bottom-right corner.
- se_lng: number
-
Longitude of boundig box's bottom-right corner.
- nw_lat: number
-
Latitude of boundig box's top-left corner.
- nw_lng: number
-
Longitude of boundig box's top-left corner.
SequenceV3: object
- date_added: string
-
Date the sequence has been added.(yyyy-mm-dd (H:i)) format.
- processing: integer (int32)
-
Number of processing sequences.
- platform: string
-
Platform name.
- user: string
-
User name.
- meta_data_filename: string
-
The URL of metadata file.
- address: string
-
Address where recording started.
- reviewed: string
-
Reviewd. Available values: (0,1).
- changes: string
-
Changes.
- recognitions: string
-
Number of recognitions.
- count_active_photos: integer (int32)
-
Count of active photos.
- obd_info: string
-
OBD Info.
- owner: boolean
-
True if the logged-in user is the owner.
- photos: object[]
-
List of photos.
SequenceV4: object
- address: string
-
Address where recording started.
- platformName: string
-
Platform name.
- platformVersion: string
-
Platform version.
- appVersion: string
-
Application version.
- reviewed: string
-
Reviewd. Available values: (0,1).
- changes: string
-
Changes.
- recognitions: string
-
Number of recognitions.
- dateAdded: string
-
Date the sequence has been added.(yyyy-mm-dd (H:i)) format.
- imagesStatus: string
-
Image processing status. ('NEW','VIDEO_SPLIT','UPLOAD_FINISHED','PROCESSING_FINISHED','PROCESSING_FAILED').
- currentLat: number
-
Latitude of the sequence starting point.
- currentLng: number
-
Longitutde of the sequence starting point.
- obdInfo: string
-
OBD Info.
- metaDataFilename: string
-
The URL of metadata file.
- thumb_name: string
-
The URL of thumbnail.
- id: integer (int32)
-
Sequence ID.
- userId: integer (int32)
-
User ID.
- countryCode: string
-
Country Code.
- status: string
-
Sequence Status.
Status: object
- apiCode: integer (int32)
-
Response code.
- apiMessage: string
-
Api result message.
- executionTime: number
-
Execution time.
- httpCode: integer (int32)
-
HTTP Response code.
- httpMessage: string
-
HTTP Result message.
SucessResponse: object
- status: Status
Track: object
- element_id: integer (int32)
-
Segment ID.
- from: integer (int32)
-
From Node ID.
- to: integer (int32)
-
To Node ID.
- way_id: integer (int32)
-
Way ID.
- nw_lat: number
-
Latitude of boundig box's top-left corner.
- nw_lng: number
-
Longitude of boundig box's top-left corner.
- se_lat: number
-
Latitude of boundig box's bottom-right corner.
- se_lng: number
-
Longitude of boundig box's bottom-right corner.
- track: string[]
-
Segment geometry. List of ordered [[lat,long],[lat,long],...] values.
TracksResponse: object
- currentPageItems: object
- status: Status
- totalFilteredItems: object
- removeTracks: object
TracksStatus: object
- uploading: integer (int32)
-
Number of uploading sequences.
- processing: integer (int32)
-
Number of processing sequences.