@crvouga/mockingbird-service-google-maps 1.9.0 → 2.1.0

package/openapi.yaml

@@ -0,0 +1,747 @@
+openapi: 3.1.0
+info:
+  title: Google Places, Geocoding and Maps JavaScript API (Mockingbird subset)
+  description: |
+    The Google Maps Platform surface our member app calls: Places Autocomplete, Place Details
+    and Find Place From Text (the legacy JSON web services), the Geocoding API, and the Maps
+    JavaScript API loader (`/maps/api/js?libraries=places`). Every web-service answer is HTTP 200
+    with Google's `status` field; the mock resolves addresses from a QA corpus.
+  version: "1"
+  x-mockingbird-upstream:
+    note: >-
+      Hand-authored from Google's documented response shapes and the fields our consumer
+      reads (address-autocomplete-native-rest.tsx, address-autocomplete-web.tsx,
+      use-geocoded-address.ts). Google publishes no OpenAPI document for these endpoints.
+servers:
+  - url: https://maps.googleapis.com
+paths:
+  /maps/api/place/autocomplete/json:
+    get:
+      operationId: PlaceAutocomplete
+      x-mockingbird:
+        supported: true
+        parity:
+          enabled: true
+          safe: true
+      parameters:
+        - $ref: "#/components/parameters/Key"
+        - name: input
+          in: query
+          required: true
+          schema:
+            type: string
+            minLength: 1
+            maxLength: 60
+            examples:
+              - "1625 N Central"
+              - "Phoenix"
+              - "85004"
+              - "4821 Maple Street Denver"
+              - "200 N Spring St, Los Angeles"
+              - "136 Murray"
+        - name: types
+          in: query
+          schema:
+            type: string
+            enum: [address, geocode]
+        - name: components
+          in: query
+          schema:
+            type: string
+            enum: ["country:us", "country:ca", "country:us|country:ca"]
+        - $ref: "#/components/parameters/SessionToken"
+      responses:
+        "200":
+          description: Predictions, or a non-OK status (HTTP 200 either way)
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/AutocompleteResponse"
+        "500":
+          description: Google front-end failure (server_error preset)
+          content:
+            application/json:
+              schema:
+                type: object
+  /maps/api/place/details/json:
+    get:
+      operationId: PlaceDetails
+      x-mockingbird:
+        supported: true
+        parity:
+          enabled: true
+          safe: true
+      parameters:
+        - $ref: "#/components/parameters/Key"
+        - name: place_id
+          in: query
+          required: true
+          schema:
+            type: string
+            minLength: 1
+            maxLength: 200
+            examples:
+              - ChIJ5BKAwJuCB5951g03ZzrkHx9
+              - ChIJE1ellR5XyWiy2lHIlJ5cls3
+              - ChIJaWYsCINV1XBQQ97jO3pznpg
+              - EieyJsIjoiNDgyMSBNYXBsZSBTdHJlZXQiLCJjIjoiRGVudmVyIiwicyI6IkNPIiwieiI6IjgwMjAyIiwibiI6IkRlbnZlciBDb3VudHkiLCJhIjozOS43NDc4OCwibyI6LTEwNC45OTQyNX0
+              - ChIJdoesNotExist000000000
+        - name: fields
+          in: query
+          schema:
+            type: string
+            enum:
+              - address_component
+              - address_components
+              - geometry
+              - formatted_address,geometry
+              - place_id,name,types
+              - address_component,geometry,formatted_address
+        - $ref: "#/components/parameters/SessionToken"
+      responses:
+        "200":
+          description: The place, or a non-OK status
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/DetailsResponse"
+        "500":
+          description: Google front-end failure (server_error preset)
+          content:
+            application/json:
+              schema:
+                type: object
+  /maps/api/geocode/json:
+    get:
+      operationId: Geocode
+      x-mockingbird:
+        supported: true
+        parity:
+          enabled: true
+          safe: true
+      parameters:
+        - $ref: "#/components/parameters/Key"
+        - name: address
+          in: query
+          schema:
+            type: string
+            minLength: 1
+            maxLength: 80
+            examples:
+              - "1625 N Central Ave, Phoenix, AZ 85004"
+              - "88 Greenwich St, New York, NY 10006"
+              - "4821 Maple Street, Denver, CO 80202"
+              - "85004"
+              - "Phoenix, AZ"
+              - "1625 N Central Ave"
+        - name: place_id
+          in: query
+          schema:
+            type: string
+            examples:
+              - ChIJ5BKAwJuCB5951g03ZzrkHx9
+        - name: components
+          in: query
+          schema:
+            type: string
+            enum: ["postal_code:85004", "postal_code:10006", "postal_code:00000"]
+      responses:
+        "200":
+          description: Geocoding results, or a non-OK status
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/GeocodeResponse"
+        "500":
+          description: Google front-end failure (server_error preset)
+          content:
+            application/json:
+              schema:
+                type: object
+  /maps/api/place/findplacefromtext/json:
+    get:
+      operationId: FindPlaceFromText
+      x-mockingbird:
+        supported: true
+        parity:
+          enabled: true
+          safe: true
+      parameters:
+        - $ref: "#/components/parameters/Key"
+        - name: input
+          in: query
+          required: true
+          schema:
+            type: string
+            minLength: 1
+            maxLength: 80
+            examples:
+              - "1625 N Central Ave, Phoenix, AZ 85004"
+              - "1625 N Central"
+              - "Gilbert"
+        - name: inputtype
+          in: query
+          required: true
+          schema:
+            type: string
+            enum: [textquery, phonenumber]
+        - name: fields
+          in: query
+          schema:
+            type: string
+            enum: [geometry, "formatted_address,geometry", "place_id,name", place_id]
+      responses:
+        "200":
+          description: Candidates, or a non-OK status
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/FindPlaceResponse"
+        "500":
+          description: Google front-end failure (server_error preset)
+          content:
+            application/json:
+              schema:
+                type: object
+  /maps/api/js:
+    get:
+      operationId: MapsJavaScriptApi
+      description: >-
+        The Maps JavaScript API loader. The mock serves a shim defining google.maps.places
+        (AutocompleteService, PlacesService, AutocompleteSessionToken, PlacesServiceStatus) and
+        google.maps.Geocoder, backed by the REST operations above.
+      x-mockingbird:
+        supported: true
+        parity:
+          enabled: false
+          reason: >-
+            A JavaScript program, not data: it is exercised by evaluating it in a fake window
+            and driving our web client through it (google-maps.acceptance.test.ts).
+      parameters:
+        - name: key
+          in: query
+          schema:
+            type: string
+        - name: libraries
+          in: query
+          schema:
+            type: string
+        - name: callback
+          in: query
+          schema:
+            type: string
+        - name: v
+          in: query
+          schema:
+            type: string
+      responses:
+        "200":
+          description: The Maps JavaScript shim
+          content:
+            text/javascript:
+              schema:
+                type: string
+        "503":
+          description: Script unavailable (script_unavailable preset)
+          content:
+            text/plain:
+              schema:
+                type: string
+  /v1:validateAddress:
+    servers:
+      - url: https://addressvalidation.googleapis.com
+    post:
+      operationId: ValidateAddress
+      description: >-
+        Address Validation API v1 validateAddress, with USPS CASS data (`enableUspsCass`). A
+        Google Cloud API: errors are HTTP 4xx/5xx with a `google.rpc.Status` envelope, and the
+        key may also be sent as the `X-Goog-Api-Key` header. Responses are proto3 JSON (false
+        booleans and empty lists omitted). Reference:
+        https://developers.google.com/maps/documentation/address-validation/reference/rest/v1/TopLevel/validateAddress
+      x-mockingbird:
+        supported: true
+        parity:
+          enabled: true
+          safe: true
+      parameters:
+        - $ref: "#/components/parameters/Key"
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/ValidateAddressRequest"
+      responses:
+        "200":
+          description: The validation result
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ValidateAddressResponse"
+        "400":
+          description: INVALID_ARGUMENT (malformed request, unsupported region, invalid API key)
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/GoogleApiError"
+        "403":
+          description: PERMISSION_DENIED (missing key; address_validation_denied preset)
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/GoogleApiError"
+        "503":
+          description: UNAVAILABLE (address_validation_unavailable preset)
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/GoogleApiError"
+components:
+  parameters:
+    Key:
+      name: key
+      in: query
+      required: true
+      description: The Google Maps Platform API key (`PLACES_KEY`); also the namespace credential.
+      schema:
+        type: string
+        minLength: 1
+        maxLength: 40
+        examples: [parity-key]
+    SessionToken:
+      name: sessiontoken
+      in: query
+      description: Autocomplete session token (billing grouping); accepted and journaled as metadata.
+      schema:
+        type: string
+        format: uuid
+  schemas:
+    Status:
+      type: string
+      enum:
+        - OK
+        - ZERO_RESULTS
+        - INVALID_REQUEST
+        - OVER_QUERY_LIMIT
+        - REQUEST_DENIED
+        - UNKNOWN_ERROR
+        - NOT_FOUND
+    LatLng:
+      type: object
+      required: [lat, lng]
+      properties:
+        lat:
+          type: number
+        lng:
+          type: number
+    Viewport:
+      type: object
+      required: [northeast, southwest]
+      properties:
+        northeast:
+          $ref: "#/components/schemas/LatLng"
+        southwest:
+          $ref: "#/components/schemas/LatLng"
+    Geometry:
+      type: object
+      required: [location, viewport]
+      properties:
+        location:
+          $ref: "#/components/schemas/LatLng"
+        location_type:
+          type: string
+          enum: [ROOFTOP, RANGE_INTERPOLATED, GEOMETRIC_CENTER, APPROXIMATE]
+        viewport:
+          $ref: "#/components/schemas/Viewport"
+    AddressComponent:
+      type: object
+      required: [long_name, short_name, types]
+      properties:
+        long_name:
+          type: string
+        short_name:
+          type: string
+        types:
+          type: array
+          items:
+            type: string
+    MatchedSubstring:
+      type: object
+      required: [length, offset]
+      properties:
+        length:
+          type: integer
+        offset:
+          type: integer
+    Prediction:
+      type: object
+      required: [description, place_id, reference, structured_formatting, terms, types, matched_substrings]
+      properties:
+        description:
+          type: string
+        matched_substrings:
+          type: array
+          items:
+            $ref: "#/components/schemas/MatchedSubstring"
+        place_id:
+          type: string
+          x-mockingbird-resource:
+            type: place
+            identity: true
+        reference:
+          type: string
+        structured_formatting:
+          type: object
+          required: [main_text, secondary_text]
+          properties:
+            main_text:
+              type: string
+            main_text_matched_substrings:
+              type: array
+              items:
+                $ref: "#/components/schemas/MatchedSubstring"
+            secondary_text:
+              type: string
+        terms:
+          type: array
+          items:
+            type: object
+            required: [offset, value]
+            properties:
+              offset:
+                type: integer
+              value:
+                type: string
+        types:
+          type: array
+          items:
+            type: string
+    PlaceResult:
+      type: object
+      description: Only the fields requested with `fields=` are present.
+      properties:
+        address_components:
+          type: array
+          items:
+            $ref: "#/components/schemas/AddressComponent"
+        adr_address:
+          type: string
+        formatted_address:
+          type: string
+        geometry:
+          $ref: "#/components/schemas/Geometry"
+        name:
+          type: string
+        place_id:
+          type: string
+        reference:
+          type: string
+        types:
+          type: array
+          items:
+            type: string
+        url:
+          type: string
+        utc_offset:
+          type: integer
+        vicinity:
+          type: string
+    AutocompleteResponse:
+      type: object
+      required: [predictions, status]
+      properties:
+        predictions:
+          type: array
+          items:
+            $ref: "#/components/schemas/Prediction"
+        status:
+          $ref: "#/components/schemas/Status"
+        error_message:
+          type: string
+    DetailsResponse:
+      type: object
+      required: [html_attributions, status]
+      properties:
+        html_attributions:
+          type: array
+          items:
+            type: string
+        result:
+          $ref: "#/components/schemas/PlaceResult"
+        status:
+          $ref: "#/components/schemas/Status"
+        error_message:
+          type: string
+    GeocodeResult:
+      type: object
+      required: [address_components, formatted_address, geometry, place_id, types]
+      properties:
+        address_components:
+          type: array
+          items:
+            $ref: "#/components/schemas/AddressComponent"
+        formatted_address:
+          type: string
+        geometry:
+          $ref: "#/components/schemas/Geometry"
+        place_id:
+          type: string
+        types:
+          type: array
+          items:
+            type: string
+    GeocodeResponse:
+      type: object
+      required: [results, status]
+      properties:
+        results:
+          type: array
+          items:
+            $ref: "#/components/schemas/GeocodeResult"
+        status:
+          $ref: "#/components/schemas/Status"
+        error_message:
+          type: string
+    FindPlaceResponse:
+      type: object
+      required: [candidates, status]
+      properties:
+        candidates:
+          type: array
+          items:
+            $ref: "#/components/schemas/PlaceResult"
+        status:
+          $ref: "#/components/schemas/Status"
+        error_message:
+          type: string
+    GoogleApiError:
+      type: object
+      required: [error]
+      properties:
+        error:
+          type: object
+          required: [code, message, status]
+          properties:
+            code:
+              type: integer
+            message:
+              type: string
+            status:
+              type: string
+            details:
+              type: array
+              items:
+                type: object
+    PostalAddress:
+      type: object
+      description: google.type.PostalAddress
+      properties:
+        revision:
+          type: integer
+        regionCode:
+          type: string
+          examples: [US]
+        languageCode:
+          type: string
+        postalCode:
+          type: string
+          examples: ["85004", "10006", "80202", "90012", "00000"]
+        sortingCode:
+          type: string
+        administrativeArea:
+          type: string
+          examples: [AZ, NY, CO, CA]
+        locality:
+          type: string
+          examples: [Phoenix, New York, Denver, Los Angeles, Springfield]
+        sublocality:
+          type: string
+        addressLines:
+          type: array
+          maxItems: 3
+          items:
+            type: string
+            maxLength: 80
+            examples:
+              - "1625 N Central Ave"
+              - "1625 North Central Avenue Building A"
+              - "4821 Maple Street"
+              - "N Central Ave"
+              - "Apt 2"
+        recipients:
+          type: array
+          items:
+            type: string
+        organization:
+          type: string
+    ValidateAddressRequest:
+      type: object
+      required: [address]
+      additionalProperties: false
+      properties:
+        address:
+          $ref: "#/components/schemas/PostalAddress"
+          examples:
+            - regionCode: US
+              addressLines: ["1625 N Central Ave"]
+              locality: Phoenix
+              administrativeArea: AZ
+              postalCode: "85004"
+            - regionCode: US
+              addressLines: ["4821 Maple Street"]
+              locality: Denver
+              administrativeArea: CO
+              postalCode: "80202"
+            - regionCode: US
+              addressLines: ["N Central Ave"]
+              locality: Phoenix
+              administrativeArea: AZ
+              postalCode: "85004"
+            - regionCode: US
+              addressLines: ["1625 N Central Ave, Phoenix, AZ 85004"]
+            - regionCode: US
+              addressLines: ["12 Nowhere Rd"]
+              locality: Springfield
+              administrativeArea: ZZ
+              postalCode: "00000"
+        previousResponseId:
+          type: string
+        enableUspsCass:
+          type: boolean
+        languageOptions:
+          type: object
+        sessionToken:
+          type: string
+    ValidationAddressComponent:
+      type: object
+      required: [componentName, componentType, confirmationLevel]
+      properties:
+        componentName:
+          type: object
+          required: [text]
+          properties:
+            text:
+              type: string
+            languageCode:
+              type: string
+        componentType:
+          type: string
+        confirmationLevel:
+          type: string
+          enum: [CONFIRMED, UNCONFIRMED_BUT_PLAUSIBLE, UNCONFIRMED_AND_SUSPICIOUS]
+        inferred:
+          type: boolean
+        spellCorrected:
+          type: boolean
+        replaced:
+          type: boolean
+        unexpected:
+          type: boolean
+    Granularity:
+      type: string
+      enum: [GRANULARITY_UNSPECIFIED, SUB_PREMISE, PREMISE, PREMISE_PROXIMITY, BLOCK, ROUTE, OTHER]
+    ValidationResult:
+      type: object
+      properties:
+        verdict:
+          type: object
+          properties:
+            inputGranularity:
+              $ref: "#/components/schemas/Granularity"
+            validationGranularity:
+              $ref: "#/components/schemas/Granularity"
+            geocodeGranularity:
+              $ref: "#/components/schemas/Granularity"
+            addressComplete:
+              type: boolean
+            hasUnconfirmedComponents:
+              type: boolean
+            hasInferredComponents:
+              type: boolean
+            hasReplacedComponents:
+              type: boolean
+            hasSpellCorrectedComponents:
+              type: boolean
+            possibleNextAction:
+              type: string
+              enum: [POSSIBLE_NEXT_ACTION_UNSPECIFIED, FIX, CONFIRM_ADD_SUBPREMISES, CONFIRM, ACCEPT]
+        address:
+          type: object
+          properties:
+            formattedAddress:
+              type: string
+            postalAddress:
+              $ref: "#/components/schemas/PostalAddress"
+            addressComponents:
+              type: array
+              items:
+                $ref: "#/components/schemas/ValidationAddressComponent"
+            missingComponentTypes:
+              type: array
+              items:
+                type: string
+            unconfirmedComponentTypes:
+              type: array
+              items:
+                type: string
+            unresolvedTokens:
+              type: array
+              items:
+                type: string
+        geocode:
+          type: object
+          properties:
+            location:
+              type: object
+              properties:
+                latitude:
+                  type: number
+                longitude:
+                  type: number
+            placeId:
+              type: string
+            placeTypes:
+              type: array
+              items:
+                type: string
+        uspsData:
+          type: object
+          properties:
+            standardizedAddress:
+              type: object
+              properties:
+                firstAddressLine:
+                  type: string
+                secondAddressLine:
+                  type: string
+                cityStateZipAddressLine:
+                  type: string
+                city:
+                  type: string
+                state:
+                  type: string
+                zipCode:
+                  type: string
+                zipCodeExtension:
+                  type: string
+            dpvConfirmation:
+              type: string
+              enum: [Y, N, S, D]
+            dpvFootnote:
+              type: string
+            postOfficeCity:
+              type: string
+            postOfficeState:
+              type: string
+            errorMessage:
+              type: string
+            cassProcessed:
+              type: boolean
+    ValidateAddressResponse:
+      type: object
+      required: [result, responseId]
+      properties:
+        result:
+          $ref: "#/components/schemas/ValidationResult"
+        responseId:
+          type: string