Submissions
Crowdsourced places, entrances and fixed cameras. Never pre-filled from OSM.
← Все операции
POST/v1/places/submissionsДоступно
- Хост
https://api.atasumaps.com · createSubmission- Доступ
- API-ключ с областью: contribute + вошедший пользователь (Atasuai)
- Учёт
- Не учитывается
- Idempotency-Key
- Обязателен: один ключ на команду, повтор возвращает первый результат
Creates a ugc.reports row in pending_review (MVP: every place-type submission is reviewed by
a moderator). Edits carry base_version — the place version the user saw. Submissions are never
pre-filled with OSM content: clients must not copy displayed basemap attributes into the form,
and moderators see a warning when content looks copied. Partner shadow users may submit
but earn no jarmaq until they link an Atasuai account.
Edits can target only crowdsourced places (ugc.*): an OpenStreetMap
object has no row in our layer to change, and copying its values would break the data-plane rule,
so target_place_id: osm.* → 422 target_not_editable until the POI decision is made. OSM objects may still be named as references (parent_place_id: osm.*,
building_ref); no OSM attribute is ever stored. The payload is exactly what the user sent
(unknown fields → 400). provenance.gps_accuracy_m is also stored as the report's accuracy;
provenance.device_id must be one of the caller's registered devices (403 otherwise).
Параметры
| Имя | Где | Тип | Обязательно | Описание |
|---|
Idempotency-Key | header | string | да | Client-generated unique key per logical command (UUID v4/v7 recommended). Scope: caller + endpoint + key. Same key + same body → first result (Idempotent-Replayed: true); same key + different body → 409 idempotency_key_reused. Missing → 400 idempotency_key_required. Keys are kept at least 24 hours. |
Тело запроса SubmissionCreate
PlaceNewSubmission
| Имя | Тип | Обязательно | Описание |
|---|
kind | "place_new" | да | |
category | string | да | |
names | LocalizedText | да | Text per language. Any may be missing; clients fall back kk → ru → en. Kazakh is stored exactly as written (Ә Ғ Қ Ң Ө Ұ Ү Һ І). |
aliases | Alias[] | | |
address | Address | | Whitepaper §3 address model. A street address and a microdistrict address can coexist. All numbers are strings. |
attrs | object | | |
lnglat | LngLat | да | WGS84 [longitude, latitude] — always this order. |
access | Access | | |
parent_place_id | PlaceId | | ugc.<uuid> for our crowdsourced places and entrances, osm.n<id> / osm.w<id> / osm.r<id> for OpenStreetMap objects. Opaque to clients; used in /p/{placeId} share links. |
building_ref | integer (int64) | | OSM building way ID — a reference only; no OSM attributes are copied |
PlaceEditSubmission
| Имя | Тип | Обязательно | Описание |
|---|
kind | "place_edit" | да | |
target_place_id | PlaceId | да | ugc.<uuid> for our crowdsourced places and entrances, osm.n<id> / osm.w<id> / osm.r<id> for OpenStreetMap objects. Opaque to clients; used in /p/{placeId} share links. |
base_version | integer | да | version of the place the user saw |
changes | object | да | |
EntranceSubmission
| Имя | Тип | Обязательно | Описание |
|---|
kind | "entrance" | да | |
lnglat | LngLat | да | WGS84 [longitude, latitude] — always this order. |
ref | string | | Entrance number as written |
flats | string | | |
entrance_type | EntranceType | да | |
access | Access | да | |
parent_place_id | PlaceId | | ugc.<uuid> for our crowdsourced places and entrances, osm.n<id> / osm.w<id> / osm.r<id> for OpenStreetMap objects. Opaque to clients; used in /p/{placeId} share links. |
building_ref | integer (int64) | | OSM building way ID (reference only) |
address | Address | | Whitepaper §3 address model. A street address and a microdistrict address can coexist. All numbers are strings. |
FixedCameraSubmission
| Имя | Тип | Обязательно | Описание |
|---|
kind | "fixed_camera" | да | |
lnglat | LngLat | да | WGS84 [longitude, latitude] — always this order. |
heading_deg | integer | | Direction the camera enforces |
camera_type | "speed" | "red_light" | "average_speed" | "sergek" | "other" | да | |
speed_limit_kmh | integer | | |
Ответы
| Статус | Описание | Тип |
|---|
201 | Submission accepted for review | SubmissionCreated |
400 | Invalid request (invalid_request, idempotency_key_required, limit_exceeded, future_departure_not_supported, observation_in_future) | Problem |
401 | Missing or invalid credentials (unauthenticated, key_invalid, key_revoked, token_expired, token_invalid) | Problem |
403 | Authenticated but not allowed (scope_denied, key_restriction_failed, forbidden, user_banned, mfa_required, self_moderation_forbidden, feature_disabled) | Problem |
404 | No such resource, or not visible to the caller (not_found) | Problem |
409 | Conflict — never a silent overwrite. Codes: idempotency_key_reused (same key, different body), version_conflict (stale expected_version; body has current_version), invalid_state (transition not allowed from the current status), appeal_already_used, base_version_stale (place changed since the edit's baseline; rebase first), later_edits_exist (revert needs compensation), already_claimed, last_owner, already_member, deletion_pending. A retry with the original Idempotency-Key still returns the original result, never a 409. | Problem |
422 | Understood but cannot be done (outside_coverage, no_route, unresolvable_waypoint, too_far_from_report, event_type_disabled, no_evidence, target_not_editable) | Problem |
429 | Rate limit (rate_limited) or monthly plan quota (quota_exceeded: reject plans only; Retry-After = seconds until the next Asia/Almaty month; context = product, included, used, period_end) | Problem |