openapi: 3.0.1 info: title: Address Search Connector - Internal API version: '1' description: | **Internal API Contract for Address Search Connectors** This API defines the standard contract that all address search provider connectors must implement. The address-search-api service will call these endpoints to retrieve address data from the underlying provider (Regio, Loqate, etc.). **Implementation Notes:** - This is an internal service-to-service API (not exposed externally) - Connectors must map provider-specific responses to this standard contract - Connectors handle provider authentication, rate limiting, and error handling - Connectors should cache results when appropriate to reduce provider API calls **Connector Responsibilities:** 1. Authenticate with the provider (API keys, OAuth, etc.) 2. Transform search queries to provider-specific format 3. Map provider responses to standardised Plumery address model 4. Handle provider-specific errors and translate to standard error codes 5. Implement retry logic and circuit breakers for provider reliability servers: - url: 'https://api.plumery.com' description: Live Server paths: '/internal/v1/address-suggestions': get: tags: - Address Search Connector summary: Search addresses via provider description: | Internal endpoint called by address-search-api to search for addresses using the underlying provider. The connector transforms the standardised request to provider-specific format and returns standardised results. operationId: searchAddresses x-internal: true parameters: - name: address in: query required: true description: Partial address search query (minimum 3 characters recommended) schema: type: string minLength: 1 example: "Narva mnt 7" - name: country in: query required: false description: ISO alpha-2 country code to limit search scope schema: type: string minLength: 2 maxLength: 2 example: "EE" - name: limit in: query required: false description: Maximum number of suggestions to return schema: type: integer minimum: 1 maximum: 50 default: 10 example: 10 - name: language in: query required: false description: | ISO alpha-2 language code for address formatting and display preferences. Affects how addresses are formatted and returned by the provider (e.g., "en", "et", "fr"). Not all providers support all languages - unsupported languages will fallback to provider defaults. schema: type: string minLength: 2 maxLength: 2 pattern: '^[a-z]{2}$' example: "et" responses: '200': description: Successful search operation content: application/json: schema: $ref: '#/components/schemas/AddressSearchResponse' '400': description: Invalid request parameters content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Provider error or internal error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '/internal/v1/address-suggestions/{addressId}': get: tags: - Address Search Connector summary: Retrieve complete address details from provider description: | Internal endpoint called by address-search-api to retrieve full address details using a provider-specific address ID. The connector must transform the provider's detailed response into Plumery's standard address model. operationId: getAddressDetails parameters: - name: addressId in: path required: true description: Provider-specific address identifier (from search results) schema: type: string example: "EE_ADR_12345" responses: '200': description: Successful operation content: application/json: schema: $ref: '#/components/schemas/AddressDetails' '404': description: Address not found in provider content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Provider error or internal error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' components: schemas: AddressSearchResponse: type: object required: - suggestions properties: suggestions: type: array description: List of address suggestions from provider items: $ref: '#/components/schemas/AddressSuggestion' AddressSuggestion: type: object required: - id - address properties: id: type: string description: | Provider-specific address identifier. This ID will be used to retrieve full address details. Must be opaque and usable in subsequent requests. example: "EE_ADR_12345_TALLINN_NARVAMNT7" address: type: string description: Formatted address string suitable for display example: "Narva mnt 7, 10117 Tallinn, Estonia" AddressDetails: type: object required: - id - country description: | Complete standardised address details. Connectors must map provider-specific fields to this standard Plumery address model. Fields may be null if the provider doesn't supply that data. properties: id: type: string description: Provider-specific address identifier example: "EE_ADR_12345_TALLINN_NARVAMNT7" address: type: string description: Formatted address string suitable for display example: "Narva mnt 7, 10117 Tallinn, Estonia" streetName: type: string nullable: true description: Name of a street or thoroughfare example: "Narva mnt" buildingNumber: type: string nullable: true description: Number that identifies the position of a building on a street example: "7" buildingName: type: string nullable: true description: Name of the building or house example: "Solaris Center" floor: type: string nullable: true description: Floor or storey within a building example: "3" postBox: type: string nullable: true description: Post office box number example: "PO Box 123" suite: type: string nullable: true description: Building room number or apartment number example: "Suite 301" postCode: type: string nullable: true description: Postal code identifier example: "10117" townName: type: string nullable: true description: Name of a built-up area with defined boundaries example: "Tallinn" townLocationName: type: string nullable: true description: Specific location name within the town example: "Kesklinn" districtName: type: string nullable: true description: Subdivision within a country sub-division example: "Kesklinna linnaosa" countrySubDivision: type: string nullable: true description: State, region, county, or other country subdivision example: "Harju maakond" country: type: string description: ISO alpha-2 country code minLength: 2 maxLength: 2 example: "EE" language: type: string nullable: true description: | ISO alpha-2 language code indicating the language used for formatting this address. Reflects the actual language used by the provider to format field values. Connectors should return the language code if known, or null if provider doesn't support language selection. minLength: 2 maxLength: 2 pattern: '^[a-z]{2}$' example: "et" additionalData: type: object nullable: true description: | Provider-specific additional data that doesn't map to standard fields. Stored as key-value pairs for potential future use or debugging. additionalProperties: type: string example: adsCoid: "123456" providerQuality: "high" ErrorResponse: type: object required: - code - message properties: code: type: string description: | Standard error code. Connectors should translate provider errors to these codes: - INVALID_REQUEST - Bad request parameters - PROVIDER_ERROR - Provider returned an error - PROVIDER_UNAVAILABLE - Cannot reach provider - RATE_LIMIT_EXCEEDED - Provider rate limit hit - AUTHENTICATION_FAILED - Provider authentication failed - ADDRESS_NOT_FOUND - Address ID not found - INTERNAL_ERROR - Connector internal error example: "PROVIDER_ERROR" message: type: string description: Human-readable error message example: "Provider returned invalid response" requestId: type: string nullable: true description: Unique request identifier for debugging example: "44a5a68f-40f4-4f6d-89e8-20d74e16dddf" providerErrorCode: type: string nullable: true description: Original provider-specific error code (for debugging) example: "REGIO_ERR_123" providerErrorMessage: type: string nullable: true description: Original provider error message (for debugging) example: "Invalid ADS code format"