{
  "openapi": "3.1.0",
  "info": {
    "title": "Colapii Maps & Location",
    "version": "0.2.0",
    "description": "Unified developer platform with Communications, Data Validation & Enrichment, and Maps & Location. Maps & Location provides separate Test and Live endpoints; other families are design-only. Payments is internal billing infrastructure, not a sold API family. Default provider unavailable; explicit synthetic fixtures or configured self-hosted OSM adapter. Licensed, pinned GeoNames city search supplements are bundled as an explicit empty-result fallback; other geography requires configured owned infrastructure."
  },
  "x-platform-product-families": [
    {
      "id": "communications",
      "name": "Communications",
      "implementation": "planned"
    },
    {
      "id": "data-validation-enrichment",
      "name": "Data Validation & Enrichment",
      "implementation": "planned"
    },
    {
      "id": "maps-location",
      "name": "Maps & Location",
      "implementation": "local-test"
    }
  ],
  "x-billing-boundary": {
    "kind": "internal-infrastructure",
    "implementation": "usage-observation-only",
    "mode": "disabled",
    "chargesEnabled": false
  },
  "servers": [
    {
      "url": "https://api.colapii.com/test",
      "description": "Test environment. Real geographic data; Test keys only. 1000 admitted requests per operation per account per UTC day. No charges."
    },
    {
      "url": "https://api.colapii.com",
      "description": "Live environment. Request Live access, then administrator approval; Live keys only. Billing disabled."
    }
  ],
  "security": [
    {
      "ProjectKey": []
    }
  ],
  "paths": {
    "/v1/projects/{projectId}/location/search": {
      "post": {
        "operationId": "locationSearch",
        "tags": [
          "Location"
        ],
        "summary": "Search within verified active regional coverage",
        "description": "Test and Live use the configured Nigeria Nominatim/OSRM data, with separate keys and quotas. Missing provider infrastructure fails closed. Test keys cannot authorize Live endpoints or vice versa. Server resolves tenant/project/scopes from the credential. The path must match the authenticated project. An approved scoped search may use Google Places as an additional address lookup after a healthy local miss. Search can use separately pinned indexes of original OpenStreetMap address tags after a healthy, fully validated owned-geocoder response. Exact numbered matches retain source houseNumber and street fields. Optional addr:full matches return provider=owned-osm, source=openstreetmap and address.freeform with their own source datasetVersion, which may differ from the geocoder snapshot. Display the returned label or original freeform text and preserve attribution; do not infer houseNumber or street fields, a verified home address or an entrance from that unparsed text. Existing valid exact numbered matches take priority over the text supplement. The optional literal-address supplement preserves original decimal and House/Flat/Shop number identities in the separate nigeria-osm-literal-20261114 snapshot; 1.0 is distinct from 1, and House 20 is distinct from 20. Optional named OSM business and amenity addresses use nigeria-osm-business-addresses-20261114, kind=poi and original name, address tags and source coordinates. Original houseNumber/street and unparsed freeform fields may coexist only when independently present in the source; no city, number, opening status or entrance is inferred. Numeric brand names remain literal names. Address-like numeric names require matching original number/street tags. Optional named highway ways use osm-ng-streets-20261114, kind=street and original name/street. Their coordinates are source-line midpoints, not homes, entrances or navigation arrival points. source-line-geometry-contained state attribution is proven by the complete source geometry against pinned full-resolution state boundaries, not by its representative point. Street locality qualifiers require explicit source labels; state-only matches do not prove city coverage. Both catalogs require active sealed-artifact replay and are search-only. Local supplements never conceal provider failures or malformed upstream responses. Search may use pinned, locally served GeoNames or GRID3 settlement records after a healthy validated OSM search yields no usable result. Settlement source names/coordinates and separate provenance are retained. State agreement is checked against pinned boundaries. Exact namesakes can return multiple records; whole-word partial matches retain their original labels. Optional city context uses a documented 20 km proximity filter, not an administrative boundary. These settlement points are not numbered addresses or building entrances. Search can also return separately attributed GRID3 health facilities v4 (2026), with original facility names/points and unknown current opening status, and Overture POIs from an offline pinned index. These include optional original freeform address text; kind=poi identifies a destination, not a verified home address or building entrance. The optional GRID3 school catalog returns original school names, points, state/LGA/ward labels and sourceAgency tags under grid3-ng-schools-2020-20240426. Its publisher release is September 2020 and service data edit is April 2024; neither is a school survey date. Current operating status is unknown. Publisher and underlying-source terms remain applicable, and Colapii index/adaptation contributions use CC BY-SA 4.0. Historical NMIS school records from 2009–2014 may be used only after newer public catalogs have no match. Their original sourceDate, CC BY-SA 4.0 license and unknown current status are explicit. The optional GRID3 public destination catalog adds original locations and names from the September 2020 release for markets, post offices, police stations and government buildings. These records omit unverified numbered addresses and entrances. Their sourceRecord details describe the publisher record, and current operation is unknown. Reverse and route cannot use these supplemental indexes. Region is an entitlement/coverage selector, not proof that data exists. Scope: location:search. Each record uses the envelope provider and dataset. An approved Google Places result can carry additional per-place attribution. The region must equal the requested region and the route profile must equal the requested profile. These cross-field rules require semantic validation beyond JSON Schema. The pinned Nigeria directory from Who’s On First can supply exact named places and their supported administrative context after a healthy search has no usable match. These results carry source=whosonfirst and the original place ID and coordinates. A locality point does not establish a street address or an entrance. Opt in using addressSearch to validate an intended area, filter candidates, reuse verified shared addresses locally, and obtain short-lived selection handles. Scoped search defaults to 20 results and publishes continuation only when the provider supplies it. Suggest uses local sources. An eligible submitted search can use Google Text Search after a local miss and Place Details to obtain a missing coordinate for a single validated result. Local outages do not activate fallback.",
        "x-response-invariants": [
          "record-provider-and-dataset-equal-envelope",
          "region-equals-request",
          "result-count-within-request-limit"
        ],
        "security": [
          {
            "ProjectKey": []
          }
        ],
        "x-required-scope": "location:search",
        "x-product-family": "maps-location",
        "parameters": [
          {
            "name": "projectId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "description": "UTF-8 application/json, maximum 16 KiB. Reject unknown properties and ambiguous duplicate object keys. Coordinates use WGS84 decimal degrees.",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SearchRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Operational provider result. Synthetic examples must remain visibly labeled; empty search/reverse results are valid only from a healthy provider.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              },
              "X-Request-Id": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SearchResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid JSON, ambiguous duplicate keys, unknown fields or invalid input. Generic messages do not echo supplied values.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              },
              "X-Request-Id": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/ErrorResponse"
                    },
                    {
                      "properties": {
                        "error": {
                          "properties": {
                            "code": {
                              "enum": [
                                "invalid_request"
                              ]
                            }
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid, expired or revoked project credential.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              },
              "X-Request-Id": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              },
              "WWW-Authenticate": {
                "schema": {
                  "type": "string",
                  "const": "Bearer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/ErrorResponse"
                    },
                    {
                      "properties": {
                        "error": {
                          "properties": {
                            "code": {
                              "enum": [
                                "unauthorized"
                              ]
                            }
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "403": {
            "description": "Credential does not authorize this project, region or operation; same generic response for unknown projects.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              },
              "X-Request-Id": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/ErrorResponse"
                    },
                    {
                      "properties": {
                        "error": {
                          "properties": {
                            "code": {
                              "enum": [
                                "forbidden"
                              ]
                            }
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "413": {
            "description": "Body larger than 16 KiB.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              },
              "X-Request-Id": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/ErrorResponse"
                    },
                    {
                      "properties": {
                        "error": {
                          "properties": {
                            "code": {
                              "enum": [
                                "invalid_request"
                              ]
                            }
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "415": {
            "description": "Unsupported content type; UTF-8 application/json required.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              },
              "X-Request-Id": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/ErrorResponse"
                    },
                    {
                      "properties": {
                        "error": {
                          "properties": {
                            "code": {
                              "enum": [
                                "invalid_request"
                              ]
                            }
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "422": {
            "description": "Outside configured operational coverage; route may also return no_route.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              },
              "X-Request-Id": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/ErrorResponse"
                    },
                    {
                      "properties": {
                        "error": {
                          "properties": {
                            "code": {
                              "enum": [
                                "outside_coverage",
                                "unknown_locality"
                              ]
                            }
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "429": {
            "description": "Project operation quota exhausted; retry delay supplied.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              },
              "X-Request-Id": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              },
              "Retry-After": {
                "description": "Whole seconds until retry is eligible.",
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/ErrorResponse"
                    },
                    {
                      "properties": {
                        "error": {
                          "properties": {
                            "code": {
                              "enum": [
                                "rate_limited",
                                "daily_quota_exceeded"
                              ]
                            }
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "500": {
            "description": "Unexpected internal failure; no stack or upstream response disclosed.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              },
              "X-Request-Id": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/ErrorResponse"
                    },
                    {
                      "properties": {
                        "error": {
                          "properties": {
                            "code": {
                              "enum": [
                                "internal_error"
                              ]
                            }
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "503": {
            "description": "Provider/dataset or required identity, quota or accounting dependency unavailable.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              },
              "X-Request-Id": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/ErrorResponse"
                    },
                    {
                      "properties": {
                        "error": {
                          "properties": {
                            "code": {
                              "enum": [
                                "provider_unavailable",
                                "dependency_unavailable"
                              ]
                            }
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/v1/projects/{projectId}/location/reverse": {
      "post": {
        "operationId": "locationReverse",
        "tags": [
          "Location"
        ],
        "summary": "Reverse within verified active regional coverage",
        "description": "Test and Live use the configured Nigeria Nominatim/OSRM data, with separate keys and quotas. Missing provider infrastructure fails closed. Test keys cannot authorize Live endpoints or vice versa. Server resolves tenant/project/scopes from the credential. The path must match the authenticated project. An approved scoped search may use Google Places as an additional address lookup after a healthy local miss. Search can use separately pinned indexes of original OpenStreetMap address tags after a healthy, fully validated owned-geocoder response. Exact numbered matches retain source houseNumber and street fields. Optional addr:full matches return provider=owned-osm, source=openstreetmap and address.freeform with their own source datasetVersion, which may differ from the geocoder snapshot. Display the returned label or original freeform text and preserve attribution; do not infer houseNumber or street fields, a verified home address or an entrance from that unparsed text. Existing valid exact numbered matches take priority over the text supplement. The optional literal-address supplement preserves original decimal and House/Flat/Shop number identities in the separate nigeria-osm-literal-20261114 snapshot; 1.0 is distinct from 1, and House 20 is distinct from 20. Optional named OSM business and amenity addresses use nigeria-osm-business-addresses-20261114, kind=poi and original name, address tags and source coordinates. Original houseNumber/street and unparsed freeform fields may coexist only when independently present in the source; no city, number, opening status or entrance is inferred. Numeric brand names remain literal names. Address-like numeric names require matching original number/street tags. Optional named highway ways use osm-ng-streets-20261114, kind=street and original name/street. Their coordinates are source-line midpoints, not homes, entrances or navigation arrival points. source-line-geometry-contained state attribution is proven by the complete source geometry against pinned full-resolution state boundaries, not by its representative point. Street locality qualifiers require explicit source labels; state-only matches do not prove city coverage. Both catalogs require active sealed-artifact replay and are search-only. Local supplements never conceal provider failures or malformed upstream responses. Search may use pinned, locally served GeoNames or GRID3 settlement records after a healthy validated OSM search yields no usable result. Settlement source names/coordinates and separate provenance are retained. State agreement is checked against pinned boundaries. Exact namesakes can return multiple records; whole-word partial matches retain their original labels. Optional city context uses a documented 20 km proximity filter, not an administrative boundary. These settlement points are not numbered addresses or building entrances. Search can also return separately attributed GRID3 health facilities v4 (2026), with original facility names/points and unknown current opening status, and Overture POIs from an offline pinned index. These include optional original freeform address text; kind=poi identifies a destination, not a verified home address or building entrance. The optional GRID3 school catalog returns original school names, points, state/LGA/ward labels and sourceAgency tags under grid3-ng-schools-2020-20240426. Its publisher release is September 2020 and service data edit is April 2024; neither is a school survey date. Current operating status is unknown. Publisher and underlying-source terms remain applicable, and Colapii index/adaptation contributions use CC BY-SA 4.0. Historical NMIS school records from 2009–2014 may be used only after newer public catalogs have no match. Their original sourceDate, CC BY-SA 4.0 license and unknown current status are explicit. The optional GRID3 public destination catalog adds original locations and names from the September 2020 release for markets, post offices, police stations and government buildings. These records omit unverified numbered addresses and entrances. Their sourceRecord details describe the publisher record, and current operation is unknown. Reverse and route cannot use these supplemental indexes. Region is an entitlement/coverage selector, not proof that data exists. Scope: location:reverse. Each record uses the envelope provider and dataset. An approved Google Places result can carry additional per-place attribution. The region must equal the requested region and the route profile must equal the requested profile. These cross-field rules require semantic validation beyond JSON Schema.",
        "x-response-invariants": [
          "record-provider-and-dataset-equal-envelope",
          "region-equals-request",
          "result-count-within-request-limit"
        ],
        "security": [
          {
            "ProjectKey": []
          }
        ],
        "x-required-scope": "location:reverse",
        "x-product-family": "maps-location",
        "parameters": [
          {
            "name": "projectId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "description": "UTF-8 application/json, maximum 16 KiB. Reject unknown properties and ambiguous duplicate object keys. Coordinates use WGS84 decimal degrees.",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ReverseRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Operational provider result. Synthetic examples must remain visibly labeled; empty search/reverse results are valid only from a healthy provider.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              },
              "X-Request-Id": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ReverseResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid JSON, ambiguous duplicate keys, unknown fields or invalid input. Generic messages do not echo supplied values.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              },
              "X-Request-Id": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/ErrorResponse"
                    },
                    {
                      "properties": {
                        "error": {
                          "properties": {
                            "code": {
                              "enum": [
                                "invalid_request"
                              ]
                            }
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid, expired or revoked project credential.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              },
              "X-Request-Id": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              },
              "WWW-Authenticate": {
                "schema": {
                  "type": "string",
                  "const": "Bearer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/ErrorResponse"
                    },
                    {
                      "properties": {
                        "error": {
                          "properties": {
                            "code": {
                              "enum": [
                                "unauthorized"
                              ]
                            }
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "403": {
            "description": "Credential does not authorize this project, region or operation; same generic response for unknown projects.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              },
              "X-Request-Id": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/ErrorResponse"
                    },
                    {
                      "properties": {
                        "error": {
                          "properties": {
                            "code": {
                              "enum": [
                                "forbidden"
                              ]
                            }
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "413": {
            "description": "Body larger than 16 KiB.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              },
              "X-Request-Id": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/ErrorResponse"
                    },
                    {
                      "properties": {
                        "error": {
                          "properties": {
                            "code": {
                              "enum": [
                                "invalid_request"
                              ]
                            }
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "415": {
            "description": "Unsupported content type; UTF-8 application/json required.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              },
              "X-Request-Id": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/ErrorResponse"
                    },
                    {
                      "properties": {
                        "error": {
                          "properties": {
                            "code": {
                              "enum": [
                                "invalid_request"
                              ]
                            }
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "422": {
            "description": "Outside configured operational coverage; route may also return no_route.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              },
              "X-Request-Id": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/ErrorResponse"
                    },
                    {
                      "properties": {
                        "error": {
                          "properties": {
                            "code": {
                              "enum": [
                                "outside_coverage"
                              ]
                            }
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "429": {
            "description": "Project operation quota exhausted; retry delay supplied.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              },
              "X-Request-Id": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              },
              "Retry-After": {
                "description": "Whole seconds until retry is eligible.",
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/ErrorResponse"
                    },
                    {
                      "properties": {
                        "error": {
                          "properties": {
                            "code": {
                              "enum": [
                                "rate_limited",
                                "daily_quota_exceeded"
                              ]
                            }
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "500": {
            "description": "Unexpected internal failure; no stack or upstream response disclosed.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              },
              "X-Request-Id": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/ErrorResponse"
                    },
                    {
                      "properties": {
                        "error": {
                          "properties": {
                            "code": {
                              "enum": [
                                "internal_error"
                              ]
                            }
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "503": {
            "description": "Provider/dataset or required identity, quota or accounting dependency unavailable.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              },
              "X-Request-Id": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/ErrorResponse"
                    },
                    {
                      "properties": {
                        "error": {
                          "properties": {
                            "code": {
                              "enum": [
                                "provider_unavailable",
                                "dependency_unavailable"
                              ]
                            }
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/v1/projects/{projectId}/location/route": {
      "post": {
        "operationId": "locationRoute",
        "tags": [
          "Location"
        ],
        "summary": "Route within verified active regional coverage",
        "description": "Test and Live use the configured Nigeria Nominatim/OSRM data, with separate keys and quotas. Missing provider infrastructure fails closed. Test keys cannot authorize Live endpoints or vice versa. Server resolves tenant/project/scopes from the credential. The path must match the authenticated project. An approved scoped search may use Google Places as an additional address lookup after a healthy local miss. Search can use separately pinned indexes of original OpenStreetMap address tags after a healthy, fully validated owned-geocoder response. Exact numbered matches retain source houseNumber and street fields. Optional addr:full matches return provider=owned-osm, source=openstreetmap and address.freeform with their own source datasetVersion, which may differ from the geocoder snapshot. Display the returned label or original freeform text and preserve attribution; do not infer houseNumber or street fields, a verified home address or an entrance from that unparsed text. Existing valid exact numbered matches take priority over the text supplement. The optional literal-address supplement preserves original decimal and House/Flat/Shop number identities in the separate nigeria-osm-literal-20261114 snapshot; 1.0 is distinct from 1, and House 20 is distinct from 20. Optional named OSM business and amenity addresses use nigeria-osm-business-addresses-20261114, kind=poi and original name, address tags and source coordinates. Original houseNumber/street and unparsed freeform fields may coexist only when independently present in the source; no city, number, opening status or entrance is inferred. Numeric brand names remain literal names. Address-like numeric names require matching original number/street tags. Optional named highway ways use osm-ng-streets-20261114, kind=street and original name/street. Their coordinates are source-line midpoints, not homes, entrances or navigation arrival points. source-line-geometry-contained state attribution is proven by the complete source geometry against pinned full-resolution state boundaries, not by its representative point. Street locality qualifiers require explicit source labels; state-only matches do not prove city coverage. Both catalogs require active sealed-artifact replay and are search-only. Local supplements never conceal provider failures or malformed upstream responses. Search may use pinned, locally served GeoNames or GRID3 settlement records after a healthy validated OSM search yields no usable result. Settlement source names/coordinates and separate provenance are retained. State agreement is checked against pinned boundaries. Exact namesakes can return multiple records; whole-word partial matches retain their original labels. Optional city context uses a documented 20 km proximity filter, not an administrative boundary. These settlement points are not numbered addresses or building entrances. Search can also return separately attributed GRID3 health facilities v4 (2026), with original facility names/points and unknown current opening status, and Overture POIs from an offline pinned index. These include optional original freeform address text; kind=poi identifies a destination, not a verified home address or building entrance. The optional GRID3 school catalog returns original school names, points, state/LGA/ward labels and sourceAgency tags under grid3-ng-schools-2020-20240426. Its publisher release is September 2020 and service data edit is April 2024; neither is a school survey date. Current operating status is unknown. Publisher and underlying-source terms remain applicable, and Colapii index/adaptation contributions use CC BY-SA 4.0. Historical NMIS school records from 2009–2014 may be used only after newer public catalogs have no match. Their original sourceDate, CC BY-SA 4.0 license and unknown current status are explicit. The optional GRID3 public destination catalog adds original locations and names from the September 2020 release for markets, post offices, police stations and government buildings. These records omit unverified numbered addresses and entrances. Their sourceRecord details describe the publisher record, and current operation is unknown. Reverse and route cannot use these supplemental indexes. Region is an entitlement/coverage selector, not proof that data exists. Scope: location:route. Each record uses the envelope provider and dataset. An approved Google Places result can carry additional per-place attribution. The region must equal the requested region and the route profile must equal the requested profile. These cross-field rules require semantic validation beyond JSON Schema. Coordinates remain supported. Each route endpoint can instead use a current project-bound selection from scoped search. Its coordinates are passed directly to Colapii routing and endpointSources identifies the address source separately. After bounded owned snapping fails for an identified numbered house, an approved project can use Places Text Search to correct the exact endpoint within the same city. A successful correction permits one additional Colapii route attempt. Colapii calculates all geometry, distance and duration.",
        "x-response-invariants": [
          "record-provider-and-dataset-equal-envelope",
          "region-equals-request",
          "profile-equals-request"
        ],
        "security": [
          {
            "ProjectKey": []
          }
        ],
        "x-required-scope": "location:route",
        "x-product-family": "maps-location",
        "parameters": [
          {
            "name": "projectId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "description": "UTF-8 application/json, maximum 16 KiB. Reject unknown properties and ambiguous duplicate object keys. Coordinates use WGS84 decimal degrees.",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RouteRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Operational provider result. Synthetic examples must remain visibly labeled; empty search/reverse results are valid only from a healthy provider.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              },
              "X-Request-Id": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RouteResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid JSON, ambiguous duplicate keys, unknown fields or invalid input. Generic messages do not echo supplied values.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              },
              "X-Request-Id": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/ErrorResponse"
                    },
                    {
                      "properties": {
                        "error": {
                          "properties": {
                            "code": {
                              "enum": [
                                "invalid_request"
                              ]
                            }
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid, expired or revoked project credential.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              },
              "X-Request-Id": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              },
              "WWW-Authenticate": {
                "schema": {
                  "type": "string",
                  "const": "Bearer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/ErrorResponse"
                    },
                    {
                      "properties": {
                        "error": {
                          "properties": {
                            "code": {
                              "enum": [
                                "unauthorized"
                              ]
                            }
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "403": {
            "description": "Credential does not authorize this project, region or operation; same generic response for unknown projects.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              },
              "X-Request-Id": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/ErrorResponse"
                    },
                    {
                      "properties": {
                        "error": {
                          "properties": {
                            "code": {
                              "enum": [
                                "forbidden"
                              ]
                            }
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "413": {
            "description": "Body larger than 16 KiB.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              },
              "X-Request-Id": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/ErrorResponse"
                    },
                    {
                      "properties": {
                        "error": {
                          "properties": {
                            "code": {
                              "enum": [
                                "invalid_request"
                              ]
                            }
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "415": {
            "description": "Unsupported content type; UTF-8 application/json required.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              },
              "X-Request-Id": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/ErrorResponse"
                    },
                    {
                      "properties": {
                        "error": {
                          "properties": {
                            "code": {
                              "enum": [
                                "invalid_request"
                              ]
                            }
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "422": {
            "description": "Outside configured operational coverage; route may also return no_route.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              },
              "X-Request-Id": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/ErrorResponse"
                    },
                    {
                      "properties": {
                        "error": {
                          "properties": {
                            "code": {
                              "enum": [
                                "outside_coverage",
                                "no_route",
                                "endpoint_unresolved"
                              ]
                            }
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "429": {
            "description": "Project operation quota exhausted; retry delay supplied.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              },
              "X-Request-Id": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              },
              "Retry-After": {
                "description": "Whole seconds until retry is eligible.",
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/ErrorResponse"
                    },
                    {
                      "properties": {
                        "error": {
                          "properties": {
                            "code": {
                              "enum": [
                                "rate_limited",
                                "daily_quota_exceeded"
                              ]
                            }
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "500": {
            "description": "Unexpected internal failure; no stack or upstream response disclosed.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              },
              "X-Request-Id": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/ErrorResponse"
                    },
                    {
                      "properties": {
                        "error": {
                          "properties": {
                            "code": {
                              "enum": [
                                "internal_error"
                              ]
                            }
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "503": {
            "description": "Provider/dataset or required identity, quota or accounting dependency unavailable.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              },
              "X-Request-Id": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/ErrorResponse"
                    },
                    {
                      "properties": {
                        "error": {
                          "properties": {
                            "code": {
                              "enum": [
                                "provider_unavailable",
                                "dependency_unavailable"
                              ]
                            }
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/v1/projects/{projectId}/location/contributions/save": {
      "post": {
        "operationId": "private_contributions_save",
        "tags": [
          "Private locations"
        ],
        "summary": "contributions/save",
        "description": "Private project/environment namespace. No shared map publication. New explicit read/write key scopes required. Independently collected addresses require the versioned rights declaration; Google response content is forbidden. Google references store opaque place IDs only and perform no provider calls. Save is create-once: same clientReference and same payload returns the same record; a changed or deleted payload returns 409. Live payload retention is 90 days; Test is 1 day. Maximum 10000 lifetime records per Live project (100 Test), 100000 globally, and 100 saves per day per namespace. Lookup is exact address + state, at most 10 records. Address content is encrypted at rest; expired/deleted payloads are removed. Minimal opaque tombstones prevent resurrection. Existing public search does not read these records.",
        "security": [
          {
            "ProjectKey": []
          }
        ],
        "x-required-scope": "location:contributions:write",
        "x-product-family": "maps-location",
        "parameters": [
          {
            "name": "projectId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "properties": {
                  "region": {
                    "type": "string",
                    "const": "nigeria"
                  },
                  "clientReference": {
                    "type": "string",
                    "minLength": 16,
                    "maxLength": 100,
                    "pattern": "^[A-Za-z0-9_-]+$"
                  },
                  "address": {
                    "type": "string",
                    "minLength": 5,
                    "maxLength": 500,
                    "pattern": "^[^\\u0000-\\u001f\\u007f]+$"
                  },
                  "state": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 40,
                    "pattern": "^[^\\u0000-\\u001f\\u007f]+$"
                  },
                  "coordinate": {
                    "type": "object",
                    "additionalProperties": false,
                    "properties": {
                      "lat": {
                        "type": "number",
                        "minimum": 3.8,
                        "maximum": 14.5
                      },
                      "lon": {
                        "type": "number",
                        "minimum": 2.1,
                        "maximum": 15.4
                      }
                    },
                    "required": [
                      "lat",
                      "lon"
                    ]
                  },
                  "source": {
                    "type": "string",
                    "enum": [
                      "partner-survey",
                      "direct-user-entry"
                    ]
                  },
                  "observedAt": {
                    "type": "string",
                    "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
                  },
                  "rightsProfile": {
                    "const": "independent-private-v1"
                  },
                  "storagePermission": {
                    "const": true
                  },
                  "independentOfRestrictedProviders": {
                    "const": true
                  }
                },
                "required": [
                  "region",
                  "clientReference",
                  "address",
                  "state",
                  "source",
                  "observedAt",
                  "rightsProfile",
                  "storagePermission",
                  "independentOfRestrictedProviders"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Private data only. Not a shared map record.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "const": "no-store"
                }
              },
              "X-Request-Id": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "requestId": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "data": {
                      "type": "object",
                      "additionalProperties": false,
                      "properties": {
                        "id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "visibility": {
                          "const": "private"
                        },
                        "createdAt": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "expiresAt": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "verification": {
                          "const": "partner-asserted"
                        },
                        "clientReference": {
                          "type": "string",
                          "minLength": 16,
                          "maxLength": 100,
                          "pattern": "^[A-Za-z0-9_-]+$"
                        },
                        "address": {
                          "type": "string",
                          "minLength": 5,
                          "maxLength": 500,
                          "pattern": "^[^\\u0000-\\u001f\\u007f]+$"
                        },
                        "state": {
                          "type": "string",
                          "minLength": 1,
                          "maxLength": 40,
                          "pattern": "^[^\\u0000-\\u001f\\u007f]+$"
                        },
                        "country": {
                          "const": "Nigeria"
                        },
                        "coordinate": {
                          "type": "object",
                          "additionalProperties": false,
                          "properties": {
                            "lat": {
                              "type": "number",
                              "minimum": 3.8,
                              "maximum": 14.5
                            },
                            "lon": {
                              "type": "number",
                              "minimum": 2.1,
                              "maximum": 15.4
                            }
                          },
                          "required": [
                            "lat",
                            "lon"
                          ]
                        },
                        "source": {
                          "type": "string",
                          "enum": [
                            "partner-survey",
                            "direct-user-entry"
                          ]
                        },
                        "observedAt": {
                          "type": "string",
                          "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
                        },
                        "rightsProfile": {
                          "const": "independent-private-v1"
                        },
                        "storagePermission": {
                          "const": true
                        },
                        "independentOfRestrictedProviders": {
                          "const": true
                        }
                      },
                      "required": [
                        "id",
                        "visibility",
                        "createdAt",
                        "expiresAt",
                        "verification",
                        "clientReference",
                        "address",
                        "state",
                        "country",
                        "source",
                        "observedAt",
                        "rightsProfile",
                        "storagePermission",
                        "independentOfRestrictedProviders"
                      ]
                    }
                  },
                  "required": [
                    "requestId",
                    "data"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Bounded failure without submitted content.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "const": "no-store"
                }
              },
              "X-Request-Id": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "requestId": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "error": {
                      "type": "object",
                      "additionalProperties": false,
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            "invalid_request"
                          ]
                        },
                        "message": {
                          "type": "string",
                          "minLength": 1,
                          "maxLength": 200,
                          "pattern": "^[^\\u0000-\\u001f\\u007f]+$"
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "requestId",
                    "error"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Bounded failure without submitted content.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "const": "no-store"
                }
              },
              "X-Request-Id": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              },
              "WWW-Authenticate": {
                "schema": {
                  "const": "Bearer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "requestId": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "error": {
                      "type": "object",
                      "additionalProperties": false,
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            "unauthorized"
                          ]
                        },
                        "message": {
                          "type": "string",
                          "minLength": 1,
                          "maxLength": 200,
                          "pattern": "^[^\\u0000-\\u001f\\u007f]+$"
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "requestId",
                    "error"
                  ]
                }
              }
            }
          },
          "403": {
            "description": "Bounded failure without submitted content.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "const": "no-store"
                }
              },
              "X-Request-Id": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "requestId": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "error": {
                      "type": "object",
                      "additionalProperties": false,
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            "forbidden"
                          ]
                        },
                        "message": {
                          "type": "string",
                          "minLength": 1,
                          "maxLength": 200,
                          "pattern": "^[^\\u0000-\\u001f\\u007f]+$"
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "requestId",
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "Bounded failure without submitted content.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "const": "no-store"
                }
              },
              "X-Request-Id": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "requestId": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "error": {
                      "type": "object",
                      "additionalProperties": false,
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            "not_found"
                          ]
                        },
                        "message": {
                          "type": "string",
                          "minLength": 1,
                          "maxLength": 200,
                          "pattern": "^[^\\u0000-\\u001f\\u007f]+$"
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "requestId",
                    "error"
                  ]
                }
              }
            }
          },
          "409": {
            "description": "Bounded failure without submitted content.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "const": "no-store"
                }
              },
              "X-Request-Id": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "requestId": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "error": {
                      "type": "object",
                      "additionalProperties": false,
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            "conflict"
                          ]
                        },
                        "message": {
                          "type": "string",
                          "minLength": 1,
                          "maxLength": 200,
                          "pattern": "^[^\\u0000-\\u001f\\u007f]+$"
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "requestId",
                    "error"
                  ]
                }
              }
            }
          },
          "413": {
            "description": "Bounded failure without submitted content.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "const": "no-store"
                }
              },
              "X-Request-Id": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "requestId": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "error": {
                      "type": "object",
                      "additionalProperties": false,
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            "invalid_request"
                          ]
                        },
                        "message": {
                          "type": "string",
                          "minLength": 1,
                          "maxLength": 200,
                          "pattern": "^[^\\u0000-\\u001f\\u007f]+$"
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "requestId",
                    "error"
                  ]
                }
              }
            }
          },
          "415": {
            "description": "Bounded failure without submitted content.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "const": "no-store"
                }
              },
              "X-Request-Id": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "requestId": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "error": {
                      "type": "object",
                      "additionalProperties": false,
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            "invalid_request"
                          ]
                        },
                        "message": {
                          "type": "string",
                          "minLength": 1,
                          "maxLength": 200,
                          "pattern": "^[^\\u0000-\\u001f\\u007f]+$"
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "requestId",
                    "error"
                  ]
                }
              }
            }
          },
          "429": {
            "description": "Bounded failure without submitted content.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "const": "no-store"
                }
              },
              "X-Request-Id": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              },
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "requestId": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "error": {
                      "type": "object",
                      "additionalProperties": false,
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            "rate_limited",
                            "storage_limit"
                          ]
                        },
                        "message": {
                          "type": "string",
                          "minLength": 1,
                          "maxLength": 200,
                          "pattern": "^[^\\u0000-\\u001f\\u007f]+$"
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "requestId",
                    "error"
                  ]
                }
              }
            }
          },
          "500": {
            "description": "Bounded failure without submitted content.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "const": "no-store"
                }
              },
              "X-Request-Id": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "requestId": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "error": {
                      "type": "object",
                      "additionalProperties": false,
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            "internal_error"
                          ]
                        },
                        "message": {
                          "type": "string",
                          "minLength": 1,
                          "maxLength": 200,
                          "pattern": "^[^\\u0000-\\u001f\\u007f]+$"
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "requestId",
                    "error"
                  ]
                }
              }
            }
          },
          "503": {
            "description": "Bounded failure without submitted content.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "const": "no-store"
                }
              },
              "X-Request-Id": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "requestId": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "error": {
                      "type": "object",
                      "additionalProperties": false,
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            "dependency_unavailable"
                          ]
                        },
                        "message": {
                          "type": "string",
                          "minLength": 1,
                          "maxLength": 200,
                          "pattern": "^[^\\u0000-\\u001f\\u007f]+$"
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "requestId",
                    "error"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/v1/projects/{projectId}/location/contributions/get": {
      "post": {
        "operationId": "private_contributions_get",
        "tags": [
          "Private locations"
        ],
        "summary": "contributions/get",
        "description": "Private project/environment namespace. No shared map publication. New explicit read/write key scopes required. Independently collected addresses require the versioned rights declaration; Google response content is forbidden. Google references store opaque place IDs only and perform no provider calls. Save is create-once: same clientReference and same payload returns the same record; a changed or deleted payload returns 409. Live payload retention is 90 days; Test is 1 day. Maximum 10000 lifetime records per Live project (100 Test), 100000 globally, and 100 saves per day per namespace. Lookup is exact address + state, at most 10 records. Address content is encrypted at rest; expired/deleted payloads are removed. Minimal opaque tombstones prevent resurrection. Existing public search does not read these records.",
        "security": [
          {
            "ProjectKey": []
          }
        ],
        "x-required-scope": "location:contributions:read",
        "x-product-family": "maps-location",
        "parameters": [
          {
            "name": "projectId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "properties": {
                  "region": {
                    "type": "string",
                    "const": "nigeria"
                  },
                  "clientReference": {
                    "type": "string",
                    "minLength": 16,
                    "maxLength": 100,
                    "pattern": "^[A-Za-z0-9_-]+$"
                  }
                },
                "required": [
                  "region",
                  "clientReference"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Private data only. Not a shared map record.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "const": "no-store"
                }
              },
              "X-Request-Id": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "requestId": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "data": {
                      "type": "object",
                      "additionalProperties": false,
                      "properties": {
                        "id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "visibility": {
                          "const": "private"
                        },
                        "createdAt": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "expiresAt": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "verification": {
                          "const": "partner-asserted"
                        },
                        "clientReference": {
                          "type": "string",
                          "minLength": 16,
                          "maxLength": 100,
                          "pattern": "^[A-Za-z0-9_-]+$"
                        },
                        "address": {
                          "type": "string",
                          "minLength": 5,
                          "maxLength": 500,
                          "pattern": "^[^\\u0000-\\u001f\\u007f]+$"
                        },
                        "state": {
                          "type": "string",
                          "minLength": 1,
                          "maxLength": 40,
                          "pattern": "^[^\\u0000-\\u001f\\u007f]+$"
                        },
                        "country": {
                          "const": "Nigeria"
                        },
                        "coordinate": {
                          "type": "object",
                          "additionalProperties": false,
                          "properties": {
                            "lat": {
                              "type": "number",
                              "minimum": 3.8,
                              "maximum": 14.5
                            },
                            "lon": {
                              "type": "number",
                              "minimum": 2.1,
                              "maximum": 15.4
                            }
                          },
                          "required": [
                            "lat",
                            "lon"
                          ]
                        },
                        "source": {
                          "type": "string",
                          "enum": [
                            "partner-survey",
                            "direct-user-entry"
                          ]
                        },
                        "observedAt": {
                          "type": "string",
                          "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
                        },
                        "rightsProfile": {
                          "const": "independent-private-v1"
                        },
                        "storagePermission": {
                          "const": true
                        },
                        "independentOfRestrictedProviders": {
                          "const": true
                        }
                      },
                      "required": [
                        "id",
                        "visibility",
                        "createdAt",
                        "expiresAt",
                        "verification",
                        "clientReference",
                        "address",
                        "state",
                        "country",
                        "source",
                        "observedAt",
                        "rightsProfile",
                        "storagePermission",
                        "independentOfRestrictedProviders"
                      ]
                    }
                  },
                  "required": [
                    "requestId",
                    "data"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Bounded failure without submitted content.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "const": "no-store"
                }
              },
              "X-Request-Id": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "requestId": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "error": {
                      "type": "object",
                      "additionalProperties": false,
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            "invalid_request"
                          ]
                        },
                        "message": {
                          "type": "string",
                          "minLength": 1,
                          "maxLength": 200,
                          "pattern": "^[^\\u0000-\\u001f\\u007f]+$"
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "requestId",
                    "error"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Bounded failure without submitted content.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "const": "no-store"
                }
              },
              "X-Request-Id": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              },
              "WWW-Authenticate": {
                "schema": {
                  "const": "Bearer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "requestId": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "error": {
                      "type": "object",
                      "additionalProperties": false,
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            "unauthorized"
                          ]
                        },
                        "message": {
                          "type": "string",
                          "minLength": 1,
                          "maxLength": 200,
                          "pattern": "^[^\\u0000-\\u001f\\u007f]+$"
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "requestId",
                    "error"
                  ]
                }
              }
            }
          },
          "403": {
            "description": "Bounded failure without submitted content.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "const": "no-store"
                }
              },
              "X-Request-Id": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "requestId": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "error": {
                      "type": "object",
                      "additionalProperties": false,
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            "forbidden"
                          ]
                        },
                        "message": {
                          "type": "string",
                          "minLength": 1,
                          "maxLength": 200,
                          "pattern": "^[^\\u0000-\\u001f\\u007f]+$"
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "requestId",
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "Bounded failure without submitted content.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "const": "no-store"
                }
              },
              "X-Request-Id": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "requestId": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "error": {
                      "type": "object",
                      "additionalProperties": false,
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            "not_found"
                          ]
                        },
                        "message": {
                          "type": "string",
                          "minLength": 1,
                          "maxLength": 200,
                          "pattern": "^[^\\u0000-\\u001f\\u007f]+$"
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "requestId",
                    "error"
                  ]
                }
              }
            }
          },
          "409": {
            "description": "Bounded failure without submitted content.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "const": "no-store"
                }
              },
              "X-Request-Id": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "requestId": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "error": {
                      "type": "object",
                      "additionalProperties": false,
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            "conflict"
                          ]
                        },
                        "message": {
                          "type": "string",
                          "minLength": 1,
                          "maxLength": 200,
                          "pattern": "^[^\\u0000-\\u001f\\u007f]+$"
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "requestId",
                    "error"
                  ]
                }
              }
            }
          },
          "413": {
            "description": "Bounded failure without submitted content.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "const": "no-store"
                }
              },
              "X-Request-Id": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "requestId": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "error": {
                      "type": "object",
                      "additionalProperties": false,
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            "invalid_request"
                          ]
                        },
                        "message": {
                          "type": "string",
                          "minLength": 1,
                          "maxLength": 200,
                          "pattern": "^[^\\u0000-\\u001f\\u007f]+$"
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "requestId",
                    "error"
                  ]
                }
              }
            }
          },
          "415": {
            "description": "Bounded failure without submitted content.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "const": "no-store"
                }
              },
              "X-Request-Id": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "requestId": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "error": {
                      "type": "object",
                      "additionalProperties": false,
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            "invalid_request"
                          ]
                        },
                        "message": {
                          "type": "string",
                          "minLength": 1,
                          "maxLength": 200,
                          "pattern": "^[^\\u0000-\\u001f\\u007f]+$"
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "requestId",
                    "error"
                  ]
                }
              }
            }
          },
          "429": {
            "description": "Bounded failure without submitted content.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "const": "no-store"
                }
              },
              "X-Request-Id": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              },
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "requestId": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "error": {
                      "type": "object",
                      "additionalProperties": false,
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            "rate_limited",
                            "storage_limit"
                          ]
                        },
                        "message": {
                          "type": "string",
                          "minLength": 1,
                          "maxLength": 200,
                          "pattern": "^[^\\u0000-\\u001f\\u007f]+$"
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "requestId",
                    "error"
                  ]
                }
              }
            }
          },
          "500": {
            "description": "Bounded failure without submitted content.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "const": "no-store"
                }
              },
              "X-Request-Id": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "requestId": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "error": {
                      "type": "object",
                      "additionalProperties": false,
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            "internal_error"
                          ]
                        },
                        "message": {
                          "type": "string",
                          "minLength": 1,
                          "maxLength": 200,
                          "pattern": "^[^\\u0000-\\u001f\\u007f]+$"
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "requestId",
                    "error"
                  ]
                }
              }
            }
          },
          "503": {
            "description": "Bounded failure without submitted content.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "const": "no-store"
                }
              },
              "X-Request-Id": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "requestId": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "error": {
                      "type": "object",
                      "additionalProperties": false,
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            "dependency_unavailable"
                          ]
                        },
                        "message": {
                          "type": "string",
                          "minLength": 1,
                          "maxLength": 200,
                          "pattern": "^[^\\u0000-\\u001f\\u007f]+$"
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "requestId",
                    "error"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/v1/projects/{projectId}/location/contributions/lookup": {
      "post": {
        "operationId": "private_contributions_lookup",
        "tags": [
          "Private locations"
        ],
        "summary": "contributions/lookup",
        "description": "Private project/environment namespace. No shared map publication. New explicit read/write key scopes required. Independently collected addresses require the versioned rights declaration; Google response content is forbidden. Google references store opaque place IDs only and perform no provider calls. Save is create-once: same clientReference and same payload returns the same record; a changed or deleted payload returns 409. Live payload retention is 90 days; Test is 1 day. Maximum 10000 lifetime records per Live project (100 Test), 100000 globally, and 100 saves per day per namespace. Lookup is exact address + state, at most 10 records. Address content is encrypted at rest; expired/deleted payloads are removed. Minimal opaque tombstones prevent resurrection. Existing public search does not read these records.",
        "security": [
          {
            "ProjectKey": []
          }
        ],
        "x-required-scope": "location:contributions:read",
        "x-product-family": "maps-location",
        "parameters": [
          {
            "name": "projectId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "properties": {
                  "region": {
                    "type": "string",
                    "const": "nigeria"
                  },
                  "address": {
                    "type": "string",
                    "minLength": 5,
                    "maxLength": 500,
                    "pattern": "^[^\\u0000-\\u001f\\u007f]+$"
                  },
                  "state": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 40,
                    "pattern": "^[^\\u0000-\\u001f\\u007f]+$"
                  }
                },
                "required": [
                  "region",
                  "address",
                  "state"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Private data only. Not a shared map record.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "const": "no-store"
                }
              },
              "X-Request-Id": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "requestId": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "data": {
                      "type": "array",
                      "maxItems": 10,
                      "items": {
                        "type": "object",
                        "additionalProperties": false,
                        "properties": {
                          "id": {
                            "type": "string",
                            "format": "uuid"
                          },
                          "visibility": {
                            "const": "private"
                          },
                          "createdAt": {
                            "type": "integer",
                            "minimum": 0
                          },
                          "expiresAt": {
                            "type": "integer",
                            "minimum": 0
                          },
                          "verification": {
                            "const": "partner-asserted"
                          },
                          "clientReference": {
                            "type": "string",
                            "minLength": 16,
                            "maxLength": 100,
                            "pattern": "^[A-Za-z0-9_-]+$"
                          },
                          "address": {
                            "type": "string",
                            "minLength": 5,
                            "maxLength": 500,
                            "pattern": "^[^\\u0000-\\u001f\\u007f]+$"
                          },
                          "state": {
                            "type": "string",
                            "minLength": 1,
                            "maxLength": 40,
                            "pattern": "^[^\\u0000-\\u001f\\u007f]+$"
                          },
                          "country": {
                            "const": "Nigeria"
                          },
                          "coordinate": {
                            "type": "object",
                            "additionalProperties": false,
                            "properties": {
                              "lat": {
                                "type": "number",
                                "minimum": 3.8,
                                "maximum": 14.5
                              },
                              "lon": {
                                "type": "number",
                                "minimum": 2.1,
                                "maximum": 15.4
                              }
                            },
                            "required": [
                              "lat",
                              "lon"
                            ]
                          },
                          "source": {
                            "type": "string",
                            "enum": [
                              "partner-survey",
                              "direct-user-entry"
                            ]
                          },
                          "observedAt": {
                            "type": "string",
                            "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
                          },
                          "rightsProfile": {
                            "const": "independent-private-v1"
                          },
                          "storagePermission": {
                            "const": true
                          },
                          "independentOfRestrictedProviders": {
                            "const": true
                          }
                        },
                        "required": [
                          "id",
                          "visibility",
                          "createdAt",
                          "expiresAt",
                          "verification",
                          "clientReference",
                          "address",
                          "state",
                          "country",
                          "source",
                          "observedAt",
                          "rightsProfile",
                          "storagePermission",
                          "independentOfRestrictedProviders"
                        ]
                      }
                    }
                  },
                  "required": [
                    "requestId",
                    "data"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Bounded failure without submitted content.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "const": "no-store"
                }
              },
              "X-Request-Id": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "requestId": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "error": {
                      "type": "object",
                      "additionalProperties": false,
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            "invalid_request"
                          ]
                        },
                        "message": {
                          "type": "string",
                          "minLength": 1,
                          "maxLength": 200,
                          "pattern": "^[^\\u0000-\\u001f\\u007f]+$"
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "requestId",
                    "error"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Bounded failure without submitted content.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "const": "no-store"
                }
              },
              "X-Request-Id": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              },
              "WWW-Authenticate": {
                "schema": {
                  "const": "Bearer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "requestId": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "error": {
                      "type": "object",
                      "additionalProperties": false,
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            "unauthorized"
                          ]
                        },
                        "message": {
                          "type": "string",
                          "minLength": 1,
                          "maxLength": 200,
                          "pattern": "^[^\\u0000-\\u001f\\u007f]+$"
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "requestId",
                    "error"
                  ]
                }
              }
            }
          },
          "403": {
            "description": "Bounded failure without submitted content.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "const": "no-store"
                }
              },
              "X-Request-Id": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "requestId": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "error": {
                      "type": "object",
                      "additionalProperties": false,
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            "forbidden"
                          ]
                        },
                        "message": {
                          "type": "string",
                          "minLength": 1,
                          "maxLength": 200,
                          "pattern": "^[^\\u0000-\\u001f\\u007f]+$"
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "requestId",
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "Bounded failure without submitted content.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "const": "no-store"
                }
              },
              "X-Request-Id": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "requestId": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "error": {
                      "type": "object",
                      "additionalProperties": false,
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            "not_found"
                          ]
                        },
                        "message": {
                          "type": "string",
                          "minLength": 1,
                          "maxLength": 200,
                          "pattern": "^[^\\u0000-\\u001f\\u007f]+$"
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "requestId",
                    "error"
                  ]
                }
              }
            }
          },
          "409": {
            "description": "Bounded failure without submitted content.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "const": "no-store"
                }
              },
              "X-Request-Id": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "requestId": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "error": {
                      "type": "object",
                      "additionalProperties": false,
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            "conflict"
                          ]
                        },
                        "message": {
                          "type": "string",
                          "minLength": 1,
                          "maxLength": 200,
                          "pattern": "^[^\\u0000-\\u001f\\u007f]+$"
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "requestId",
                    "error"
                  ]
                }
              }
            }
          },
          "413": {
            "description": "Bounded failure without submitted content.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "const": "no-store"
                }
              },
              "X-Request-Id": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "requestId": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "error": {
                      "type": "object",
                      "additionalProperties": false,
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            "invalid_request"
                          ]
                        },
                        "message": {
                          "type": "string",
                          "minLength": 1,
                          "maxLength": 200,
                          "pattern": "^[^\\u0000-\\u001f\\u007f]+$"
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "requestId",
                    "error"
                  ]
                }
              }
            }
          },
          "415": {
            "description": "Bounded failure without submitted content.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "const": "no-store"
                }
              },
              "X-Request-Id": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "requestId": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "error": {
                      "type": "object",
                      "additionalProperties": false,
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            "invalid_request"
                          ]
                        },
                        "message": {
                          "type": "string",
                          "minLength": 1,
                          "maxLength": 200,
                          "pattern": "^[^\\u0000-\\u001f\\u007f]+$"
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "requestId",
                    "error"
                  ]
                }
              }
            }
          },
          "429": {
            "description": "Bounded failure without submitted content.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "const": "no-store"
                }
              },
              "X-Request-Id": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              },
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "requestId": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "error": {
                      "type": "object",
                      "additionalProperties": false,
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            "rate_limited",
                            "storage_limit"
                          ]
                        },
                        "message": {
                          "type": "string",
                          "minLength": 1,
                          "maxLength": 200,
                          "pattern": "^[^\\u0000-\\u001f\\u007f]+$"
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "requestId",
                    "error"
                  ]
                }
              }
            }
          },
          "500": {
            "description": "Bounded failure without submitted content.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "const": "no-store"
                }
              },
              "X-Request-Id": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "requestId": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "error": {
                      "type": "object",
                      "additionalProperties": false,
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            "internal_error"
                          ]
                        },
                        "message": {
                          "type": "string",
                          "minLength": 1,
                          "maxLength": 200,
                          "pattern": "^[^\\u0000-\\u001f\\u007f]+$"
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "requestId",
                    "error"
                  ]
                }
              }
            }
          },
          "503": {
            "description": "Bounded failure without submitted content.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "const": "no-store"
                }
              },
              "X-Request-Id": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "requestId": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "error": {
                      "type": "object",
                      "additionalProperties": false,
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            "dependency_unavailable"
                          ]
                        },
                        "message": {
                          "type": "string",
                          "minLength": 1,
                          "maxLength": 200,
                          "pattern": "^[^\\u0000-\\u001f\\u007f]+$"
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "requestId",
                    "error"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/v1/projects/{projectId}/location/contributions/delete": {
      "post": {
        "operationId": "private_contributions_delete",
        "tags": [
          "Private locations"
        ],
        "summary": "contributions/delete",
        "description": "Private project/environment namespace. No shared map publication. New explicit read/write key scopes required. Independently collected addresses require the versioned rights declaration; Google response content is forbidden. Google references store opaque place IDs only and perform no provider calls. Save is create-once: same clientReference and same payload returns the same record; a changed or deleted payload returns 409. Live payload retention is 90 days; Test is 1 day. Maximum 10000 lifetime records per Live project (100 Test), 100000 globally, and 100 saves per day per namespace. Lookup is exact address + state, at most 10 records. Address content is encrypted at rest; expired/deleted payloads are removed. Minimal opaque tombstones prevent resurrection. Existing public search does not read these records.",
        "security": [
          {
            "ProjectKey": []
          }
        ],
        "x-required-scope": "location:contributions:write",
        "x-product-family": "maps-location",
        "parameters": [
          {
            "name": "projectId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "properties": {
                  "region": {
                    "type": "string",
                    "const": "nigeria"
                  },
                  "clientReference": {
                    "type": "string",
                    "minLength": 16,
                    "maxLength": 100,
                    "pattern": "^[A-Za-z0-9_-]+$"
                  }
                },
                "required": [
                  "region",
                  "clientReference"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Private data only. Not a shared map record.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "const": "no-store"
                }
              },
              "X-Request-Id": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "requestId": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "deleted": {
                      "const": true
                    }
                  },
                  "required": [
                    "requestId",
                    "deleted"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Bounded failure without submitted content.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "const": "no-store"
                }
              },
              "X-Request-Id": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "requestId": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "error": {
                      "type": "object",
                      "additionalProperties": false,
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            "invalid_request"
                          ]
                        },
                        "message": {
                          "type": "string",
                          "minLength": 1,
                          "maxLength": 200,
                          "pattern": "^[^\\u0000-\\u001f\\u007f]+$"
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "requestId",
                    "error"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Bounded failure without submitted content.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "const": "no-store"
                }
              },
              "X-Request-Id": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              },
              "WWW-Authenticate": {
                "schema": {
                  "const": "Bearer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "requestId": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "error": {
                      "type": "object",
                      "additionalProperties": false,
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            "unauthorized"
                          ]
                        },
                        "message": {
                          "type": "string",
                          "minLength": 1,
                          "maxLength": 200,
                          "pattern": "^[^\\u0000-\\u001f\\u007f]+$"
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "requestId",
                    "error"
                  ]
                }
              }
            }
          },
          "403": {
            "description": "Bounded failure without submitted content.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "const": "no-store"
                }
              },
              "X-Request-Id": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "requestId": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "error": {
                      "type": "object",
                      "additionalProperties": false,
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            "forbidden"
                          ]
                        },
                        "message": {
                          "type": "string",
                          "minLength": 1,
                          "maxLength": 200,
                          "pattern": "^[^\\u0000-\\u001f\\u007f]+$"
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "requestId",
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "Bounded failure without submitted content.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "const": "no-store"
                }
              },
              "X-Request-Id": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "requestId": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "error": {
                      "type": "object",
                      "additionalProperties": false,
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            "not_found"
                          ]
                        },
                        "message": {
                          "type": "string",
                          "minLength": 1,
                          "maxLength": 200,
                          "pattern": "^[^\\u0000-\\u001f\\u007f]+$"
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "requestId",
                    "error"
                  ]
                }
              }
            }
          },
          "409": {
            "description": "Bounded failure without submitted content.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "const": "no-store"
                }
              },
              "X-Request-Id": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "requestId": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "error": {
                      "type": "object",
                      "additionalProperties": false,
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            "conflict"
                          ]
                        },
                        "message": {
                          "type": "string",
                          "minLength": 1,
                          "maxLength": 200,
                          "pattern": "^[^\\u0000-\\u001f\\u007f]+$"
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "requestId",
                    "error"
                  ]
                }
              }
            }
          },
          "413": {
            "description": "Bounded failure without submitted content.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "const": "no-store"
                }
              },
              "X-Request-Id": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "requestId": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "error": {
                      "type": "object",
                      "additionalProperties": false,
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            "invalid_request"
                          ]
                        },
                        "message": {
                          "type": "string",
                          "minLength": 1,
                          "maxLength": 200,
                          "pattern": "^[^\\u0000-\\u001f\\u007f]+$"
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "requestId",
                    "error"
                  ]
                }
              }
            }
          },
          "415": {
            "description": "Bounded failure without submitted content.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "const": "no-store"
                }
              },
              "X-Request-Id": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "requestId": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "error": {
                      "type": "object",
                      "additionalProperties": false,
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            "invalid_request"
                          ]
                        },
                        "message": {
                          "type": "string",
                          "minLength": 1,
                          "maxLength": 200,
                          "pattern": "^[^\\u0000-\\u001f\\u007f]+$"
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "requestId",
                    "error"
                  ]
                }
              }
            }
          },
          "429": {
            "description": "Bounded failure without submitted content.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "const": "no-store"
                }
              },
              "X-Request-Id": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              },
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "requestId": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "error": {
                      "type": "object",
                      "additionalProperties": false,
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            "rate_limited",
                            "storage_limit"
                          ]
                        },
                        "message": {
                          "type": "string",
                          "minLength": 1,
                          "maxLength": 200,
                          "pattern": "^[^\\u0000-\\u001f\\u007f]+$"
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "requestId",
                    "error"
                  ]
                }
              }
            }
          },
          "500": {
            "description": "Bounded failure without submitted content.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "const": "no-store"
                }
              },
              "X-Request-Id": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "requestId": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "error": {
                      "type": "object",
                      "additionalProperties": false,
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            "internal_error"
                          ]
                        },
                        "message": {
                          "type": "string",
                          "minLength": 1,
                          "maxLength": 200,
                          "pattern": "^[^\\u0000-\\u001f\\u007f]+$"
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "requestId",
                    "error"
                  ]
                }
              }
            }
          },
          "503": {
            "description": "Bounded failure without submitted content.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "const": "no-store"
                }
              },
              "X-Request-Id": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "requestId": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "error": {
                      "type": "object",
                      "additionalProperties": false,
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            "dependency_unavailable"
                          ]
                        },
                        "message": {
                          "type": "string",
                          "minLength": 1,
                          "maxLength": 200,
                          "pattern": "^[^\\u0000-\\u001f\\u007f]+$"
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "requestId",
                    "error"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/v1/projects/{projectId}/location/google-place-references/save": {
      "post": {
        "operationId": "private_google_place_references_save",
        "tags": [
          "Private locations"
        ],
        "summary": "google-place-references/save",
        "description": "Private project/environment namespace. No shared map publication. New explicit read/write key scopes required. Independently collected addresses require the versioned rights declaration; Google response content is forbidden. Google references store opaque place IDs only and perform no provider calls. Save is create-once: same clientReference and same payload returns the same record; a changed or deleted payload returns 409. Live payload retention is 90 days; Test is 1 day. Maximum 10000 lifetime records per Live project (100 Test), 100000 globally, and 100 saves per day per namespace. Lookup is exact address + state, at most 10 records. Address content is encrypted at rest; expired/deleted payloads are removed. Minimal opaque tombstones prevent resurrection. Existing public search does not read these records.",
        "security": [
          {
            "ProjectKey": []
          }
        ],
        "x-required-scope": "location:contributions:write",
        "x-product-family": "maps-location",
        "parameters": [
          {
            "name": "projectId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "properties": {
                  "region": {
                    "type": "string",
                    "const": "nigeria"
                  },
                  "clientReference": {
                    "type": "string",
                    "minLength": 16,
                    "maxLength": 100,
                    "pattern": "^[A-Za-z0-9_-]+$"
                  },
                  "placeId": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 256,
                    "pattern": "^[A-Za-z0-9_-]+$"
                  }
                },
                "required": [
                  "region",
                  "clientReference",
                  "placeId"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Private data only. Not a shared map record.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "const": "no-store"
                }
              },
              "X-Request-Id": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "requestId": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "data": {
                      "type": "object",
                      "additionalProperties": false,
                      "properties": {
                        "id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "visibility": {
                          "const": "private"
                        },
                        "createdAt": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "expiresAt": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "verification": {
                          "const": "unverified-reference"
                        },
                        "clientReference": {
                          "type": "string",
                          "minLength": 16,
                          "maxLength": 100,
                          "pattern": "^[A-Za-z0-9_-]+$"
                        },
                        "provider": {
                          "const": "google"
                        },
                        "placeId": {
                          "type": "string",
                          "minLength": 1,
                          "maxLength": 256,
                          "pattern": "^[A-Za-z0-9_-]+$"
                        }
                      },
                      "required": [
                        "id",
                        "visibility",
                        "createdAt",
                        "expiresAt",
                        "verification",
                        "clientReference",
                        "provider",
                        "placeId"
                      ]
                    }
                  },
                  "required": [
                    "requestId",
                    "data"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Bounded failure without submitted content.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "const": "no-store"
                }
              },
              "X-Request-Id": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "requestId": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "error": {
                      "type": "object",
                      "additionalProperties": false,
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            "invalid_request"
                          ]
                        },
                        "message": {
                          "type": "string",
                          "minLength": 1,
                          "maxLength": 200,
                          "pattern": "^[^\\u0000-\\u001f\\u007f]+$"
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "requestId",
                    "error"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Bounded failure without submitted content.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "const": "no-store"
                }
              },
              "X-Request-Id": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              },
              "WWW-Authenticate": {
                "schema": {
                  "const": "Bearer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "requestId": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "error": {
                      "type": "object",
                      "additionalProperties": false,
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            "unauthorized"
                          ]
                        },
                        "message": {
                          "type": "string",
                          "minLength": 1,
                          "maxLength": 200,
                          "pattern": "^[^\\u0000-\\u001f\\u007f]+$"
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "requestId",
                    "error"
                  ]
                }
              }
            }
          },
          "403": {
            "description": "Bounded failure without submitted content.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "const": "no-store"
                }
              },
              "X-Request-Id": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "requestId": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "error": {
                      "type": "object",
                      "additionalProperties": false,
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            "forbidden"
                          ]
                        },
                        "message": {
                          "type": "string",
                          "minLength": 1,
                          "maxLength": 200,
                          "pattern": "^[^\\u0000-\\u001f\\u007f]+$"
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "requestId",
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "Bounded failure without submitted content.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "const": "no-store"
                }
              },
              "X-Request-Id": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "requestId": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "error": {
                      "type": "object",
                      "additionalProperties": false,
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            "not_found"
                          ]
                        },
                        "message": {
                          "type": "string",
                          "minLength": 1,
                          "maxLength": 200,
                          "pattern": "^[^\\u0000-\\u001f\\u007f]+$"
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "requestId",
                    "error"
                  ]
                }
              }
            }
          },
          "409": {
            "description": "Bounded failure without submitted content.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "const": "no-store"
                }
              },
              "X-Request-Id": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "requestId": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "error": {
                      "type": "object",
                      "additionalProperties": false,
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            "conflict"
                          ]
                        },
                        "message": {
                          "type": "string",
                          "minLength": 1,
                          "maxLength": 200,
                          "pattern": "^[^\\u0000-\\u001f\\u007f]+$"
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "requestId",
                    "error"
                  ]
                }
              }
            }
          },
          "413": {
            "description": "Bounded failure without submitted content.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "const": "no-store"
                }
              },
              "X-Request-Id": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "requestId": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "error": {
                      "type": "object",
                      "additionalProperties": false,
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            "invalid_request"
                          ]
                        },
                        "message": {
                          "type": "string",
                          "minLength": 1,
                          "maxLength": 200,
                          "pattern": "^[^\\u0000-\\u001f\\u007f]+$"
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "requestId",
                    "error"
                  ]
                }
              }
            }
          },
          "415": {
            "description": "Bounded failure without submitted content.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "const": "no-store"
                }
              },
              "X-Request-Id": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "requestId": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "error": {
                      "type": "object",
                      "additionalProperties": false,
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            "invalid_request"
                          ]
                        },
                        "message": {
                          "type": "string",
                          "minLength": 1,
                          "maxLength": 200,
                          "pattern": "^[^\\u0000-\\u001f\\u007f]+$"
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "requestId",
                    "error"
                  ]
                }
              }
            }
          },
          "429": {
            "description": "Bounded failure without submitted content.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "const": "no-store"
                }
              },
              "X-Request-Id": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              },
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "requestId": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "error": {
                      "type": "object",
                      "additionalProperties": false,
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            "rate_limited",
                            "storage_limit"
                          ]
                        },
                        "message": {
                          "type": "string",
                          "minLength": 1,
                          "maxLength": 200,
                          "pattern": "^[^\\u0000-\\u001f\\u007f]+$"
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "requestId",
                    "error"
                  ]
                }
              }
            }
          },
          "500": {
            "description": "Bounded failure without submitted content.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "const": "no-store"
                }
              },
              "X-Request-Id": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "requestId": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "error": {
                      "type": "object",
                      "additionalProperties": false,
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            "internal_error"
                          ]
                        },
                        "message": {
                          "type": "string",
                          "minLength": 1,
                          "maxLength": 200,
                          "pattern": "^[^\\u0000-\\u001f\\u007f]+$"
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "requestId",
                    "error"
                  ]
                }
              }
            }
          },
          "503": {
            "description": "Bounded failure without submitted content.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "const": "no-store"
                }
              },
              "X-Request-Id": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "requestId": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "error": {
                      "type": "object",
                      "additionalProperties": false,
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            "dependency_unavailable"
                          ]
                        },
                        "message": {
                          "type": "string",
                          "minLength": 1,
                          "maxLength": 200,
                          "pattern": "^[^\\u0000-\\u001f\\u007f]+$"
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "requestId",
                    "error"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/v1/projects/{projectId}/location/google-place-references/get": {
      "post": {
        "operationId": "private_google_place_references_get",
        "tags": [
          "Private locations"
        ],
        "summary": "google-place-references/get",
        "description": "Private project/environment namespace. No shared map publication. New explicit read/write key scopes required. Independently collected addresses require the versioned rights declaration; Google response content is forbidden. Google references store opaque place IDs only and perform no provider calls. Save is create-once: same clientReference and same payload returns the same record; a changed or deleted payload returns 409. Live payload retention is 90 days; Test is 1 day. Maximum 10000 lifetime records per Live project (100 Test), 100000 globally, and 100 saves per day per namespace. Lookup is exact address + state, at most 10 records. Address content is encrypted at rest; expired/deleted payloads are removed. Minimal opaque tombstones prevent resurrection. Existing public search does not read these records.",
        "security": [
          {
            "ProjectKey": []
          }
        ],
        "x-required-scope": "location:contributions:read",
        "x-product-family": "maps-location",
        "parameters": [
          {
            "name": "projectId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "properties": {
                  "region": {
                    "type": "string",
                    "const": "nigeria"
                  },
                  "clientReference": {
                    "type": "string",
                    "minLength": 16,
                    "maxLength": 100,
                    "pattern": "^[A-Za-z0-9_-]+$"
                  }
                },
                "required": [
                  "region",
                  "clientReference"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Private data only. Not a shared map record.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "const": "no-store"
                }
              },
              "X-Request-Id": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "requestId": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "data": {
                      "type": "object",
                      "additionalProperties": false,
                      "properties": {
                        "id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "visibility": {
                          "const": "private"
                        },
                        "createdAt": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "expiresAt": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "verification": {
                          "const": "unverified-reference"
                        },
                        "clientReference": {
                          "type": "string",
                          "minLength": 16,
                          "maxLength": 100,
                          "pattern": "^[A-Za-z0-9_-]+$"
                        },
                        "provider": {
                          "const": "google"
                        },
                        "placeId": {
                          "type": "string",
                          "minLength": 1,
                          "maxLength": 256,
                          "pattern": "^[A-Za-z0-9_-]+$"
                        }
                      },
                      "required": [
                        "id",
                        "visibility",
                        "createdAt",
                        "expiresAt",
                        "verification",
                        "clientReference",
                        "provider",
                        "placeId"
                      ]
                    }
                  },
                  "required": [
                    "requestId",
                    "data"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Bounded failure without submitted content.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "const": "no-store"
                }
              },
              "X-Request-Id": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "requestId": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "error": {
                      "type": "object",
                      "additionalProperties": false,
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            "invalid_request"
                          ]
                        },
                        "message": {
                          "type": "string",
                          "minLength": 1,
                          "maxLength": 200,
                          "pattern": "^[^\\u0000-\\u001f\\u007f]+$"
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "requestId",
                    "error"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Bounded failure without submitted content.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "const": "no-store"
                }
              },
              "X-Request-Id": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              },
              "WWW-Authenticate": {
                "schema": {
                  "const": "Bearer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "requestId": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "error": {
                      "type": "object",
                      "additionalProperties": false,
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            "unauthorized"
                          ]
                        },
                        "message": {
                          "type": "string",
                          "minLength": 1,
                          "maxLength": 200,
                          "pattern": "^[^\\u0000-\\u001f\\u007f]+$"
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "requestId",
                    "error"
                  ]
                }
              }
            }
          },
          "403": {
            "description": "Bounded failure without submitted content.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "const": "no-store"
                }
              },
              "X-Request-Id": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "requestId": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "error": {
                      "type": "object",
                      "additionalProperties": false,
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            "forbidden"
                          ]
                        },
                        "message": {
                          "type": "string",
                          "minLength": 1,
                          "maxLength": 200,
                          "pattern": "^[^\\u0000-\\u001f\\u007f]+$"
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "requestId",
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "Bounded failure without submitted content.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "const": "no-store"
                }
              },
              "X-Request-Id": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "requestId": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "error": {
                      "type": "object",
                      "additionalProperties": false,
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            "not_found"
                          ]
                        },
                        "message": {
                          "type": "string",
                          "minLength": 1,
                          "maxLength": 200,
                          "pattern": "^[^\\u0000-\\u001f\\u007f]+$"
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "requestId",
                    "error"
                  ]
                }
              }
            }
          },
          "409": {
            "description": "Bounded failure without submitted content.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "const": "no-store"
                }
              },
              "X-Request-Id": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "requestId": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "error": {
                      "type": "object",
                      "additionalProperties": false,
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            "conflict"
                          ]
                        },
                        "message": {
                          "type": "string",
                          "minLength": 1,
                          "maxLength": 200,
                          "pattern": "^[^\\u0000-\\u001f\\u007f]+$"
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "requestId",
                    "error"
                  ]
                }
              }
            }
          },
          "413": {
            "description": "Bounded failure without submitted content.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "const": "no-store"
                }
              },
              "X-Request-Id": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "requestId": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "error": {
                      "type": "object",
                      "additionalProperties": false,
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            "invalid_request"
                          ]
                        },
                        "message": {
                          "type": "string",
                          "minLength": 1,
                          "maxLength": 200,
                          "pattern": "^[^\\u0000-\\u001f\\u007f]+$"
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "requestId",
                    "error"
                  ]
                }
              }
            }
          },
          "415": {
            "description": "Bounded failure without submitted content.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "const": "no-store"
                }
              },
              "X-Request-Id": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "requestId": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "error": {
                      "type": "object",
                      "additionalProperties": false,
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            "invalid_request"
                          ]
                        },
                        "message": {
                          "type": "string",
                          "minLength": 1,
                          "maxLength": 200,
                          "pattern": "^[^\\u0000-\\u001f\\u007f]+$"
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "requestId",
                    "error"
                  ]
                }
              }
            }
          },
          "429": {
            "description": "Bounded failure without submitted content.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "const": "no-store"
                }
              },
              "X-Request-Id": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              },
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "requestId": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "error": {
                      "type": "object",
                      "additionalProperties": false,
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            "rate_limited",
                            "storage_limit"
                          ]
                        },
                        "message": {
                          "type": "string",
                          "minLength": 1,
                          "maxLength": 200,
                          "pattern": "^[^\\u0000-\\u001f\\u007f]+$"
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "requestId",
                    "error"
                  ]
                }
              }
            }
          },
          "500": {
            "description": "Bounded failure without submitted content.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "const": "no-store"
                }
              },
              "X-Request-Id": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "requestId": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "error": {
                      "type": "object",
                      "additionalProperties": false,
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            "internal_error"
                          ]
                        },
                        "message": {
                          "type": "string",
                          "minLength": 1,
                          "maxLength": 200,
                          "pattern": "^[^\\u0000-\\u001f\\u007f]+$"
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "requestId",
                    "error"
                  ]
                }
              }
            }
          },
          "503": {
            "description": "Bounded failure without submitted content.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "const": "no-store"
                }
              },
              "X-Request-Id": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "requestId": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "error": {
                      "type": "object",
                      "additionalProperties": false,
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            "dependency_unavailable"
                          ]
                        },
                        "message": {
                          "type": "string",
                          "minLength": 1,
                          "maxLength": 200,
                          "pattern": "^[^\\u0000-\\u001f\\u007f]+$"
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "requestId",
                    "error"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/v1/projects/{projectId}/location/google-place-references/delete": {
      "post": {
        "operationId": "private_google_place_references_delete",
        "tags": [
          "Private locations"
        ],
        "summary": "google-place-references/delete",
        "description": "Private project/environment namespace. No shared map publication. New explicit read/write key scopes required. Independently collected addresses require the versioned rights declaration; Google response content is forbidden. Google references store opaque place IDs only and perform no provider calls. Save is create-once: same clientReference and same payload returns the same record; a changed or deleted payload returns 409. Live payload retention is 90 days; Test is 1 day. Maximum 10000 lifetime records per Live project (100 Test), 100000 globally, and 100 saves per day per namespace. Lookup is exact address + state, at most 10 records. Address content is encrypted at rest; expired/deleted payloads are removed. Minimal opaque tombstones prevent resurrection. Existing public search does not read these records.",
        "security": [
          {
            "ProjectKey": []
          }
        ],
        "x-required-scope": "location:contributions:write",
        "x-product-family": "maps-location",
        "parameters": [
          {
            "name": "projectId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "properties": {
                  "region": {
                    "type": "string",
                    "const": "nigeria"
                  },
                  "clientReference": {
                    "type": "string",
                    "minLength": 16,
                    "maxLength": 100,
                    "pattern": "^[A-Za-z0-9_-]+$"
                  }
                },
                "required": [
                  "region",
                  "clientReference"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Private data only. Not a shared map record.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "const": "no-store"
                }
              },
              "X-Request-Id": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "requestId": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "deleted": {
                      "const": true
                    }
                  },
                  "required": [
                    "requestId",
                    "deleted"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Bounded failure without submitted content.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "const": "no-store"
                }
              },
              "X-Request-Id": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "requestId": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "error": {
                      "type": "object",
                      "additionalProperties": false,
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            "invalid_request"
                          ]
                        },
                        "message": {
                          "type": "string",
                          "minLength": 1,
                          "maxLength": 200,
                          "pattern": "^[^\\u0000-\\u001f\\u007f]+$"
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "requestId",
                    "error"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Bounded failure without submitted content.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "const": "no-store"
                }
              },
              "X-Request-Id": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              },
              "WWW-Authenticate": {
                "schema": {
                  "const": "Bearer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "requestId": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "error": {
                      "type": "object",
                      "additionalProperties": false,
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            "unauthorized"
                          ]
                        },
                        "message": {
                          "type": "string",
                          "minLength": 1,
                          "maxLength": 200,
                          "pattern": "^[^\\u0000-\\u001f\\u007f]+$"
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "requestId",
                    "error"
                  ]
                }
              }
            }
          },
          "403": {
            "description": "Bounded failure without submitted content.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "const": "no-store"
                }
              },
              "X-Request-Id": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "requestId": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "error": {
                      "type": "object",
                      "additionalProperties": false,
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            "forbidden"
                          ]
                        },
                        "message": {
                          "type": "string",
                          "minLength": 1,
                          "maxLength": 200,
                          "pattern": "^[^\\u0000-\\u001f\\u007f]+$"
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "requestId",
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "Bounded failure without submitted content.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "const": "no-store"
                }
              },
              "X-Request-Id": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "requestId": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "error": {
                      "type": "object",
                      "additionalProperties": false,
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            "not_found"
                          ]
                        },
                        "message": {
                          "type": "string",
                          "minLength": 1,
                          "maxLength": 200,
                          "pattern": "^[^\\u0000-\\u001f\\u007f]+$"
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "requestId",
                    "error"
                  ]
                }
              }
            }
          },
          "409": {
            "description": "Bounded failure without submitted content.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "const": "no-store"
                }
              },
              "X-Request-Id": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "requestId": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "error": {
                      "type": "object",
                      "additionalProperties": false,
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            "conflict"
                          ]
                        },
                        "message": {
                          "type": "string",
                          "minLength": 1,
                          "maxLength": 200,
                          "pattern": "^[^\\u0000-\\u001f\\u007f]+$"
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "requestId",
                    "error"
                  ]
                }
              }
            }
          },
          "413": {
            "description": "Bounded failure without submitted content.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "const": "no-store"
                }
              },
              "X-Request-Id": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "requestId": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "error": {
                      "type": "object",
                      "additionalProperties": false,
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            "invalid_request"
                          ]
                        },
                        "message": {
                          "type": "string",
                          "minLength": 1,
                          "maxLength": 200,
                          "pattern": "^[^\\u0000-\\u001f\\u007f]+$"
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "requestId",
                    "error"
                  ]
                }
              }
            }
          },
          "415": {
            "description": "Bounded failure without submitted content.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "const": "no-store"
                }
              },
              "X-Request-Id": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "requestId": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "error": {
                      "type": "object",
                      "additionalProperties": false,
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            "invalid_request"
                          ]
                        },
                        "message": {
                          "type": "string",
                          "minLength": 1,
                          "maxLength": 200,
                          "pattern": "^[^\\u0000-\\u001f\\u007f]+$"
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "requestId",
                    "error"
                  ]
                }
              }
            }
          },
          "429": {
            "description": "Bounded failure without submitted content.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "const": "no-store"
                }
              },
              "X-Request-Id": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              },
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "requestId": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "error": {
                      "type": "object",
                      "additionalProperties": false,
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            "rate_limited",
                            "storage_limit"
                          ]
                        },
                        "message": {
                          "type": "string",
                          "minLength": 1,
                          "maxLength": 200,
                          "pattern": "^[^\\u0000-\\u001f\\u007f]+$"
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "requestId",
                    "error"
                  ]
                }
              }
            }
          },
          "500": {
            "description": "Bounded failure without submitted content.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "const": "no-store"
                }
              },
              "X-Request-Id": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "requestId": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "error": {
                      "type": "object",
                      "additionalProperties": false,
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            "internal_error"
                          ]
                        },
                        "message": {
                          "type": "string",
                          "minLength": 1,
                          "maxLength": 200,
                          "pattern": "^[^\\u0000-\\u001f\\u007f]+$"
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "requestId",
                    "error"
                  ]
                }
              }
            }
          },
          "503": {
            "description": "Bounded failure without submitted content.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "const": "no-store"
                }
              },
              "X-Request-Id": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "requestId": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "error": {
                      "type": "object",
                      "additionalProperties": false,
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            "dependency_unavailable"
                          ]
                        },
                        "message": {
                          "type": "string",
                          "minLength": 1,
                          "maxLength": 200,
                          "pattern": "^[^\\u0000-\\u001f\\u007f]+$"
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "requestId",
                    "error"
                  ]
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ProjectKey": {
        "type": "http",
        "scheme": "bearer",
        "description": "Project-scoped high-entropy API credential; no end-user session, admin credential or client-supplied tenant claim."
      }
    },
    "schemas": {
      "AddressSearchSelectionArea": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "country": {
            "type": "string",
            "pattern": "^[a-z]{2}$"
          },
          "regionId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 120
          },
          "regionName": {
            "type": "string",
            "minLength": 1,
            "maxLength": 200
          },
          "localityId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 120
          },
          "localityName": {
            "type": "string",
            "minLength": 1,
            "maxLength": 200
          },
          "scope": {
            "type": "string",
            "enum": [
              "region",
              "locality"
            ]
          }
        },
        "required": [
          "country",
          "scope"
        ]
      },
      "AddressSearchDeviceLocation": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "lat": {
            "type": "number",
            "minimum": -90,
            "maximum": 90
          },
          "lon": {
            "type": "number",
            "minimum": -180,
            "maximum": 180
          },
          "accuracyMeters": {
            "type": "number",
            "minimum": 0,
            "maximum": 100000
          },
          "capturedAt": {
            "type": "integer",
            "minimum": 1,
            "maximum": 8640000000000000
          }
        },
        "required": [
          "lat",
          "lon",
          "accuracyMeters",
          "capturedAt"
        ]
      },
      "ScopedAddressSearch": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "sessionId": {
            "type": "string",
            "format": "uuid"
          },
          "requestVersion": {
            "type": "integer",
            "minimum": 1,
            "maximum": 2147483647
          },
          "area": {
            "$ref": "#/components/schemas/AddressSearchSelectionArea"
          },
          "deviceLocation": {
            "$ref": "#/components/schemas/AddressSearchDeviceLocation"
          },
          "requiredPrecision": {
            "type": "string",
            "enum": [
              "street",
              "house",
              "building",
              "entrance",
              "poi",
              "locality"
            ]
          },
          "action": {
            "type": "string",
            "enum": [
              "search",
              "report_missing",
              "suggest"
            ]
          },
          "cursor": {
            "type": "string",
            "pattern": "^[0-9a-f]{48}$"
          }
        },
        "required": [
          "sessionId",
          "requestVersion"
        ]
      },
      "AddressSearchArea": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "country": {
            "type": "string",
            "pattern": "^[a-z]{2}$"
          },
          "regionId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 120
          },
          "regionName": {
            "type": "string",
            "minLength": 1,
            "maxLength": 200
          },
          "localityId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 120
          },
          "localityName": {
            "type": "string",
            "minLength": 1,
            "maxLength": 200
          },
          "scope": {
            "type": "string",
            "enum": [
              "region",
              "locality"
            ]
          },
          "source": {
            "type": "string",
            "minLength": 1,
            "maxLength": 120
          },
          "sourceVersion": {
            "type": "string",
            "minLength": 1,
            "maxLength": 120
          }
        },
        "required": [
          "country",
          "regionId",
          "regionName",
          "scope",
          "source",
          "sourceVersion"
        ]
      },
      "AddressSelection": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "handle": {
            "type": "string",
            "pattern": "^[0-9a-f]{48}$"
          },
          "sessionId": {
            "type": "string",
            "format": "uuid"
          },
          "requestVersion": {
            "type": "integer",
            "minimum": 1,
            "maximum": 2147483647
          }
        },
        "required": [
          "handle",
          "sessionId",
          "requestVersion"
        ]
      },
      "SharedAddressSource": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "provider": {
            "type": "string",
            "minLength": 1,
            "maxLength": 120
          },
          "product": {
            "type": "string",
            "minLength": 1,
            "maxLength": 120
          },
          "datasetVersion": {
            "type": "string",
            "minLength": 1,
            "maxLength": 120
          },
          "recordId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 160
          },
          "retrievedAt": {
            "type": "integer",
            "minimum": 1,
            "maximum": 8640000000000000
          }
        },
        "required": [
          "provider",
          "product",
          "datasetVersion",
          "recordId",
          "retrievedAt"
        ]
      },
      "SharedAddressFieldSource": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "source": {
            "$ref": "#/components/schemas/SharedAddressSource"
          },
          "evidence": {
            "type": "string",
            "minLength": 1,
            "maxLength": 200
          }
        },
        "required": [
          "source",
          "evidence"
        ]
      },
      "SharedAddressEvidence": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "addressId": {
            "type": "string",
            "format": "uuid"
          },
          "verification": {
            "const": "verified"
          },
          "source": {
            "$ref": "#/components/schemas/SharedAddressSource"
          },
          "fieldProvenance": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "name": {
                "$ref": "#/components/schemas/SharedAddressFieldSource"
              },
              "coordinate": {
                "$ref": "#/components/schemas/SharedAddressFieldSource"
              },
              "aliases": {
                "$ref": "#/components/schemas/SharedAddressFieldSource"
              },
              "street": {
                "$ref": "#/components/schemas/SharedAddressFieldSource"
              },
              "houseNumber": {
                "$ref": "#/components/schemas/SharedAddressFieldSource"
              },
              "unit": {
                "$ref": "#/components/schemas/SharedAddressFieldSource"
              },
              "postcode": {
                "$ref": "#/components/schemas/SharedAddressFieldSource"
              }
            },
            "required": [
              "name",
              "coordinate"
            ]
          },
          "reuse": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "policyId": {
                "type": "string",
                "minLength": 1,
                "maxLength": 120
              },
              "attribution": {
                "type": "array",
                "minItems": 1,
                "maxItems": 10,
                "items": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 500
                }
              },
              "expiresAt": {
                "type": "integer",
                "minimum": 1,
                "maximum": 8640000000000000
              },
              "routable": {
                "type": "boolean"
              }
            },
            "required": [
              "policyId",
              "attribution",
              "routable"
            ]
          }
        },
        "required": [
          "addressId",
          "verification",
          "source",
          "fieldProvenance",
          "reuse"
        ]
      },
      "AddressSearchMatch": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "placeId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 120
          },
          "precision": {
            "type": "string",
            "enum": [
              "street",
              "house",
              "building",
              "entrance",
              "poi",
              "locality",
              "unknown"
            ]
          },
          "selectionHandle": {
            "type": "string",
            "pattern": "^[0-9a-f]{48}$"
          },
          "catalogue": {
            "$ref": "#/components/schemas/SharedAddressEvidence"
          }
        },
        "required": [
          "placeId",
          "precision"
        ]
      },
      "AddressSearchResponseContext": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "area": {
            "$ref": "#/components/schemas/AddressSearchArea"
          },
          "sessionId": {
            "type": "string",
            "format": "uuid"
          },
          "requestVersion": {
            "type": "integer",
            "minimum": 1,
            "maximum": 2147483647
          },
          "status": {
            "type": "string",
            "enum": [
              "matches",
              "no_local_match",
              "manual_location_required"
            ]
          },
          "deliveryMode": {
            "const": "structured"
          },
          "fallbackUsed": {
            "type": "boolean"
          },
          "fallbackState": {
            "type": "string",
            "enum": [
              "not_needed",
              "provider_not_enabled",
              "suggestions_only",
              "matched",
              "no_match",
              "unavailable"
            ]
          },
          "fallbackOutcome": {
            "type": "string",
            "enum": [
              "matches",
              "empty",
              "no_eligible_match",
              "credentials",
              "quota",
              "timeout",
              "unavailable"
            ]
          },
          "fallbackReason": {
            "type": "string",
            "enum": [
              "no_local_match",
              "only_out_of_scope_matches",
              "insufficient_address_precision",
              "user_reports_missing_place"
            ]
          },
          "requestedLimit": {
            "type": "integer",
            "minimum": 1,
            "maximum": 20
          },
          "resultCount": {
            "type": "integer",
            "minimum": 0,
            "maximum": 20
          },
          "hasMore": {
            "type": "boolean"
          },
          "nextCursor": {
            "type": "string",
            "pattern": "^[0-9a-f]{48}$"
          },
          "matches": {
            "type": "array",
            "maxItems": 20,
            "items": {
              "$ref": "#/components/schemas/AddressSearchMatch"
            }
          }
        },
        "required": [
          "area",
          "sessionId",
          "requestVersion",
          "status",
          "deliveryMode",
          "fallbackUsed",
          "fallbackState",
          "resultCount",
          "hasMore",
          "matches"
        ]
      },
      "RouteEndpointSource": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "provenance": {
            "$ref": "#/components/schemas/Provenance"
          },
          "catalogue": {
            "$ref": "#/components/schemas/SharedAddressEvidence"
          }
        },
        "required": [
          "provenance"
        ]
      },
      "RouteEndpointSources": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "origin": {
            "$ref": "#/components/schemas/RouteEndpointSource"
          },
          "destination": {
            "$ref": "#/components/schemas/RouteEndpointSource"
          }
        },
        "required": []
      },
      "Coordinate": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "lat",
          "lon"
        ],
        "properties": {
          "lat": {
            "type": "number",
            "minimum": -90,
            "maximum": 90
          },
          "lon": {
            "type": "number",
            "minimum": -180,
            "maximum": 180
          }
        }
      },
      "SearchRequest": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "query",
          "region"
        ],
        "properties": {
          "query": {
            "type": "string",
            "minLength": 1,
            "maxLength": 200,
            "pattern": "\\S",
            "description": "At least one non-whitespace character; trim before searching. No query echo in errors/logs."
          },
          "region": {
            "type": "string",
            "pattern": "^[a-z][a-z0-9-]{1,39}$"
          },
          "limit": {
            "type": "integer",
            "minimum": 1,
            "maximum": 20,
            "description": "Defaults to 20 for scoped address search and 5 for legacy search."
          },
          "addressSearch": {
            "$ref": "#/components/schemas/ScopedAddressSearch"
          }
        }
      },
      "ReverseRequest": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "coordinate",
          "region"
        ],
        "properties": {
          "coordinate": {
            "$ref": "#/components/schemas/Coordinate"
          },
          "region": {
            "type": "string",
            "pattern": "^[a-z][a-z0-9-]{1,39}$"
          }
        }
      },
      "RouteRequest": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "origin",
          "destination",
          "region",
          "profile"
        ],
        "properties": {
          "origin": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/Coordinate"
              },
              {
                "$ref": "#/components/schemas/AddressSelection"
              }
            ]
          },
          "destination": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/Coordinate"
              },
              {
                "$ref": "#/components/schemas/AddressSelection"
              }
            ]
          },
          "region": {
            "type": "string",
            "pattern": "^[a-z][a-z0-9-]{1,39}$"
          },
          "profile": {
            "type": "string",
            "enum": [
              "car",
              "bicycle",
              "pedestrian"
            ]
          }
        }
      },
      "Provenance": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "provider",
          "source",
          "datasetVersion",
          "region",
          "fixture",
          "attribution"
        ],
        "properties": {
          "provider": {
            "type": "string",
            "enum": [
              "owned-osm",
              "owned-gazetteer",
              "owned-catalogue",
              "google-places",
              "synthetic-fixture"
            ]
          },
          "source": {
            "type": "string",
            "enum": [
              "openstreetmap",
              "geonames",
              "grid3",
              "overture",
              "nmis",
              "whosonfirst",
              "colapii",
              "google",
              "synthetic"
            ]
          },
          "datasetVersion": {
            "type": "string",
            "minLength": 1,
            "maxLength": 120
          },
          "region": {
            "type": "string",
            "minLength": 1,
            "maxLength": 40
          },
          "fixture": {
            "type": "boolean"
          },
          "attribution": {
            "type": "array",
            "minItems": 1,
            "maxItems": 10,
            "items": {
              "type": "string",
              "minLength": 1,
              "maxLength": 500
            }
          }
        },
        "oneOf": [
          {
            "properties": {
              "provider": {
                "const": "owned-osm"
              },
              "source": {
                "const": "openstreetmap"
              },
              "fixture": {
                "const": false
              }
            }
          },
          {
            "properties": {
              "provider": {
                "const": "owned-gazetteer"
              },
              "source": {
                "const": "geonames"
              },
              "fixture": {
                "const": false
              },
              "datasetVersion": {
                "enum": [
                  "geonames-ng-20261101-c55f68f1",
                  "geonames-ng-cities-20261114-c84c1281",
                  "geonames-ng-settlements-20261114-c84c1281"
                ]
              },
              "region": {
                "const": "nigeria"
              }
            }
          },
          {
            "properties": {
              "provider": {
                "const": "owned-gazetteer"
              },
              "source": {
                "const": "grid3"
              },
              "fixture": {
                "const": false
              },
              "datasetVersion": {
                "enum": [
                  "grid3-ng-settlements-2020-20261114",
                  "grid3-ng-health-v4-2026",
                  "grid3-ng-schools-2020-20240426",
                  "grid3-ng-public-destinations-2020-20261115"
                ]
              },
              "region": {
                "const": "nigeria"
              }
            }
          },
          {
            "properties": {
              "provider": {
                "const": "owned-gazetteer"
              },
              "source": {
                "const": "overture"
              },
              "fixture": {
                "const": false
              },
              "datasetVersion": {
                "const": "overture-ng-places-20261021"
              },
              "region": {
                "const": "nigeria"
              }
            }
          },
          {
            "properties": {
              "provider": {
                "const": "owned-gazetteer"
              },
              "source": {
                "const": "nmis"
              },
              "fixture": {
                "const": false
              },
              "datasetVersion": {
                "const": "nmis-ng-schools-2014"
              },
              "region": {
                "const": "nigeria"
              }
            }
          },
          {
            "properties": {
              "provider": {
                "const": "owned-gazetteer"
              },
              "source": {
                "const": "whosonfirst"
              },
              "fixture": {
                "const": false
              },
              "datasetVersion": {
                "const": "wof-ng-admin-ace2a28b"
              },
              "region": {
                "const": "nigeria"
              }
            }
          },
          {
            "properties": {
              "provider": {
                "const": "owned-catalogue"
              },
              "source": {
                "const": "colapii"
              },
              "fixture": {
                "const": false
              },
              "datasetVersion": {
                "const": "colapii-shared-addresses-v1"
              }
            }
          },
          {
            "properties": {
              "provider": {
                "const": "google-places"
              },
              "source": {
                "const": "google"
              },
              "fixture": {
                "const": false
              },
              "datasetVersion": {
                "const": "google-places-v1"
              }
            }
          },
          {
            "properties": {
              "provider": {
                "const": "synthetic-fixture"
              },
              "source": {
                "const": "synthetic"
              },
              "fixture": {
                "const": true
              }
            }
          }
        ]
      },
      "DerivedStateSource": {
        "oneOf": [
          {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "source",
              "datasetVersion",
              "featureId",
              "yearRepresented",
              "method"
            ],
            "properties": {
              "source": {
                "type": "string",
                "const": "grid3-geoboundaries"
              },
              "datasetVersion": {
                "type": "string",
                "const": "NGA-ADM1-27671186"
              },
              "featureId": {
                "type": "string",
                "pattern": "^27671186B[0-9]+$",
                "maxLength": 40
              },
              "yearRepresented": {
                "type": "integer",
                "const": 2022
              },
              "method": {
                "type": "string",
                "const": "coordinate-in-polygon"
              }
            }
          },
          {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "source",
              "datasetVersion",
              "featureId",
              "yearRepresented",
              "method",
              "sourceBoundingBox"
            ],
            "properties": {
              "source": {
                "type": "string",
                "const": "grid3-geoboundaries"
              },
              "datasetVersion": {
                "type": "string",
                "const": "NGA-ADM1-27671186"
              },
              "featureId": {
                "type": "string",
                "pattern": "^27671186B[0-9]+$",
                "maxLength": 40
              },
              "yearRepresented": {
                "type": "integer",
                "const": 2022
              },
              "method": {
                "type": "string",
                "const": "source-bounding-box-contained"
              },
              "sourceBoundingBox": {
                "type": "array",
                "minItems": 4,
                "maxItems": 4,
                "items": {
                  "type": "number",
                  "minimum": 2,
                  "maximum": 16
                }
              }
            }
          },
          {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "source",
              "datasetVersion",
              "featureId",
              "yearRepresented",
              "method"
            ],
            "properties": {
              "source": {
                "type": "string",
                "const": "grid3-geoboundaries"
              },
              "datasetVersion": {
                "type": "string",
                "const": "NGA-ADM1-27671186"
              },
              "featureId": {
                "type": "string",
                "pattern": "^27671186B[0-9]+$",
                "maxLength": 40
              },
              "yearRepresented": {
                "type": "integer",
                "const": 2022
              },
              "method": {
                "type": "string",
                "const": "source-line-geometry-contained"
              }
            }
          }
        ]
      },
      "Address": {
        "type": "object",
        "additionalProperties": false,
        "required": [],
        "properties": {
          "freeform": {
            "type": "string",
            "minLength": 1,
            "maxLength": 500,
            "description": "Unparsed public source address text. Not a verified house number or entrance."
          },
          "houseNumber": {
            "type": "string",
            "minLength": 1,
            "maxLength": 40
          },
          "street": {
            "type": "string",
            "minLength": 1,
            "maxLength": 200
          },
          "unit": {
            "type": "string",
            "minLength": 1,
            "maxLength": 40
          },
          "area": {
            "type": "string",
            "minLength": 1,
            "maxLength": 200
          },
          "lga": {
            "type": "string",
            "minLength": 1,
            "maxLength": 200
          },
          "town": {
            "type": "string",
            "minLength": 1,
            "maxLength": 200
          },
          "state": {
            "type": "string",
            "minLength": 1,
            "maxLength": 200
          },
          "stateSource": {
            "$ref": "#/components/schemas/DerivedStateSource"
          },
          "country": {
            "type": "string",
            "minLength": 1,
            "maxLength": 200
          },
          "postcode": {
            "type": "string",
            "minLength": 1,
            "maxLength": 40
          },
          "lgaSource": {
            "type": "string",
            "enum": [
              "nominatim-address-county-ng",
              "grid3-settlement-admin-ng"
            ]
          }
        }
      },
      "PublicDestinationSourceRecord": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "category",
          "datasetRelease",
          "timestamp"
        ],
        "properties": {
          "category": {
            "type": "string",
            "enum": [
              "market",
              "post-office",
              "police-station",
              "government-building"
            ],
            "description": "Publisher category for the original point."
          },
          "datasetRelease": {
            "type": "string",
            "const": "2020-09"
          },
          "timestamp": {
            "type": "integer",
            "minimum": 1356998400000,
            "maximum": 1601510399999,
            "description": "Original record timestamp in epoch milliseconds."
          },
          "sourceCategory": {
            "type": "string",
            "minLength": 1,
            "maxLength": 100
          }
        }
      },
      "Place": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "id",
          "label",
          "coordinate",
          "provenance"
        ],
        "properties": {
          "id": {
            "type": "string",
            "minLength": 1,
            "maxLength": 120
          },
          "kind": {
            "type": "string",
            "enum": [
              "poi",
              "street"
            ],
            "description": "poi denotes an original named destination; street denotes an original named highway way. Neither kind establishes a verified home or entrance."
          },
          "name": {
            "type": "string",
            "minLength": 1,
            "maxLength": 200
          },
          "sourceAgency": {
            "type": "string",
            "minLength": 1,
            "maxLength": 120,
            "description": "Original source-inventory tag from the GRID3 school publisher. Not a survey date or current-operation verification."
          },
          "sourceDate": {
            "type": "string",
            "pattern": "^20(?:09|1[0-4])-\\d\\d-\\d\\d$",
            "description": "Original school survey date. Historical NMIS records only; not a current-operation guarantee."
          },
          "sourceRecord": {
            "$ref": "#/components/schemas/PublicDestinationSourceRecord"
          },
          "operatingStatus": {
            "type": "string",
            "enum": [
              "open",
              "temporarily_closed",
              "unknown"
            ]
          },
          "sourceConfidence": {
            "type": "number",
            "minimum": 0,
            "maximum": 1,
            "description": "Source estimate of POI existence; not calibrated address/coordinate accuracy or home-address verification."
          },
          "label": {
            "type": "string",
            "minLength": 1,
            "maxLength": 500
          },
          "coordinate": {
            "$ref": "#/components/schemas/Coordinate"
          },
          "provenance": {
            "$ref": "#/components/schemas/Provenance"
          },
          "address": {
            "$ref": "#/components/schemas/Address"
          }
        }
      },
      "LineString": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "type",
          "coordinates"
        ],
        "properties": {
          "type": {
            "type": "string",
            "const": "LineString"
          },
          "coordinates": {
            "type": "array",
            "minItems": 2,
            "maxItems": 10000,
            "items": {
              "type": "array",
              "prefixItems": [
                {
                  "type": "number",
                  "minimum": -180,
                  "maximum": 180
                },
                {
                  "type": "number",
                  "minimum": -90,
                  "maximum": 90
                }
              ],
              "minItems": 2,
              "maxItems": 2
            }
          }
        }
      },
      "ManeuverStep": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "type",
          "roadName",
          "coordinate",
          "distanceMeters",
          "durationSeconds"
        ],
        "properties": {
          "type": {
            "type": "string",
            "minLength": 1,
            "maxLength": 80
          },
          "modifier": {
            "type": "string",
            "minLength": 1,
            "maxLength": 80
          },
          "roadName": {
            "type": "string",
            "maxLength": 500
          },
          "coordinate": {
            "$ref": "#/components/schemas/Coordinate"
          },
          "distanceMeters": {
            "type": "number",
            "minimum": 0
          },
          "durationSeconds": {
            "type": "number",
            "minimum": 0
          }
        }
      },
      "Route": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "geometry",
          "distanceMeters",
          "durationSeconds",
          "profile",
          "provenance"
        ],
        "properties": {
          "geometry": {
            "$ref": "#/components/schemas/LineString"
          },
          "distanceMeters": {
            "type": "number",
            "minimum": 0
          },
          "durationSeconds": {
            "type": "number",
            "minimum": 0
          },
          "profile": {
            "type": "string",
            "enum": [
              "car",
              "bicycle",
              "pedestrian"
            ]
          },
          "provenance": {
            "$ref": "#/components/schemas/OSMProvenance"
          },
          "steps": {
            "type": "array",
            "minItems": 2,
            "maxItems": 2000,
            "items": {
              "$ref": "#/components/schemas/ManeuverStep"
            }
          }
        }
      },
      "SearchResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "requestId",
          "data",
          "provenance"
        ],
        "properties": {
          "requestId": {
            "type": "string",
            "format": "uuid"
          },
          "data": {
            "type": "array",
            "maxItems": 20,
            "items": {
              "$ref": "#/components/schemas/Place"
            }
          },
          "provenance": {
            "$ref": "#/components/schemas/Provenance"
          },
          "addressSearch": {
            "$ref": "#/components/schemas/AddressSearchResponseContext"
          }
        }
      },
      "ReverseResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "requestId",
          "data",
          "provenance"
        ],
        "properties": {
          "requestId": {
            "type": "string",
            "format": "uuid"
          },
          "data": {
            "type": "array",
            "maxItems": 1,
            "items": {
              "$ref": "#/components/schemas/Place"
            }
          },
          "provenance": {
            "$ref": "#/components/schemas/OSMProvenance"
          }
        }
      },
      "RouteResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "requestId",
          "data",
          "provenance"
        ],
        "properties": {
          "requestId": {
            "type": "string",
            "format": "uuid"
          },
          "data": {
            "$ref": "#/components/schemas/Route"
          },
          "provenance": {
            "$ref": "#/components/schemas/OSMProvenance"
          },
          "endpointSources": {
            "$ref": "#/components/schemas/RouteEndpointSources"
          }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "requestId",
          "error"
        ],
        "properties": {
          "requestId": {
            "type": "string",
            "format": "uuid"
          },
          "error": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "code",
              "message"
            ],
            "properties": {
              "code": {
                "type": "string",
                "enum": [
                  "invalid_request",
                  "unauthorized",
                  "forbidden",
                  "outside_coverage",
                  "unknown_locality",
                  "no_route",
                  "endpoint_unresolved",
                  "rate_limited",
                  "daily_quota_exceeded",
                  "provider_unavailable",
                  "dependency_unavailable",
                  "internal_error"
                ]
              },
              "message": {
                "type": "string",
                "minLength": 1,
                "maxLength": 200
              }
            }
          }
        }
      },
      "OSMProvenance": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "provider",
          "source",
          "datasetVersion",
          "region",
          "fixture",
          "attribution"
        ],
        "properties": {
          "provider": {
            "type": "string",
            "enum": [
              "owned-osm",
              "synthetic-fixture"
            ]
          },
          "source": {
            "type": "string",
            "enum": [
              "openstreetmap",
              "geonames",
              "grid3",
              "overture",
              "nmis",
              "whosonfirst",
              "colapii",
              "google",
              "synthetic"
            ]
          },
          "datasetVersion": {
            "type": "string",
            "minLength": 1,
            "maxLength": 120
          },
          "region": {
            "type": "string",
            "minLength": 1,
            "maxLength": 40
          },
          "fixture": {
            "type": "boolean"
          },
          "attribution": {
            "type": "array",
            "minItems": 1,
            "maxItems": 10,
            "items": {
              "type": "string",
              "minLength": 1,
              "maxLength": 500
            }
          }
        },
        "oneOf": [
          {
            "properties": {
              "provider": {
                "const": "owned-osm"
              },
              "source": {
                "const": "openstreetmap"
              },
              "fixture": {
                "const": false
              }
            }
          },
          {
            "properties": {
              "provider": {
                "const": "owned-gazetteer"
              },
              "source": {
                "const": "geonames"
              },
              "fixture": {
                "const": false
              },
              "datasetVersion": {
                "enum": [
                  "geonames-ng-20261101-c55f68f1",
                  "geonames-ng-cities-20261114-c84c1281",
                  "geonames-ng-settlements-20261114-c84c1281"
                ]
              },
              "region": {
                "const": "nigeria"
              }
            }
          },
          {
            "properties": {
              "provider": {
                "const": "owned-gazetteer"
              },
              "source": {
                "const": "grid3"
              },
              "fixture": {
                "const": false
              },
              "datasetVersion": {
                "enum": [
                  "grid3-ng-settlements-2020-20261114",
                  "grid3-ng-health-v4-2026",
                  "grid3-ng-schools-2020-20240426",
                  "grid3-ng-public-destinations-2020-20261115"
                ]
              },
              "region": {
                "const": "nigeria"
              }
            }
          },
          {
            "properties": {
              "provider": {
                "const": "owned-gazetteer"
              },
              "source": {
                "const": "overture"
              },
              "fixture": {
                "const": false
              },
              "datasetVersion": {
                "const": "overture-ng-places-20261021"
              },
              "region": {
                "const": "nigeria"
              }
            }
          },
          {
            "properties": {
              "provider": {
                "const": "owned-gazetteer"
              },
              "source": {
                "const": "nmis"
              },
              "fixture": {
                "const": false
              },
              "datasetVersion": {
                "const": "nmis-ng-schools-2014"
              },
              "region": {
                "const": "nigeria"
              }
            }
          },
          {
            "properties": {
              "provider": {
                "const": "owned-gazetteer"
              },
              "source": {
                "const": "whosonfirst"
              },
              "fixture": {
                "const": false
              },
              "datasetVersion": {
                "const": "wof-ng-admin-ace2a28b"
              },
              "region": {
                "const": "nigeria"
              }
            }
          },
          {
            "properties": {
              "provider": {
                "const": "owned-catalogue"
              },
              "source": {
                "const": "colapii"
              },
              "fixture": {
                "const": false
              },
              "datasetVersion": {
                "const": "colapii-shared-addresses-v1"
              }
            }
          },
          {
            "properties": {
              "provider": {
                "const": "google-places"
              },
              "source": {
                "const": "google"
              },
              "fixture": {
                "const": false
              },
              "datasetVersion": {
                "const": "google-places-v1"
              }
            }
          },
          {
            "properties": {
              "provider": {
                "const": "synthetic-fixture"
              },
              "source": {
                "const": "synthetic"
              },
              "fixture": {
                "const": true
              }
            }
          }
        ]
      }
    }
  }
}
