action ideal_postcodes_address_autocomplete {
  label: "Find Address"
  description: "The address autocomplete API returns a list of address suggestions that match the query ordered by relevance.\n\nThis API can be used to power realtime address finders, also known as address autofill or address autocomplete.\n\nConsider using our Address Autocomplete JavaScript libraries to add address lookup to a form in moments.\n\n## Implementing Address Autocomplete\n\nRapid address autocompletion using our Address Autocomplete API is a 2 step process.\n\n1. Retrieve partial address suggestions via `/autocomplete/addresses`\n2. Retrieve the entire address with the ID provided in the suggestion\n\nStep 2 will decrement your lookup balance.\n\nPlease note, this API is not intended to be a free standalone resource.\n\n## Filters\n\nYou can strictly narrow your result by adding filters to your querystring. For instance, you can restrict to postcode `SW1A 2AA` by appending `postcode=sw1a2aa`.\n\nIf a filter term is invalid, e.g. `postcode=SW1A2AAA`, then an empty result set is returned and no lookup is incurred.\n\nYou can also scope using multiple terms for the same filter with a comma separated list of terms. E.g. Restrict results to E1, E2 and E3 outward codes: `postcode_outward=e1,e2,e3`. Multiple terms are `OR`'ed, i.e. the matching result sets are combined.\n\nAll filters can accept multiple terms unless stated otherwise below.\n\nFilters can also be combined. E.g. Restrict results to small user organisations in the N postcode area: `su_organisation_indicator=Y&postcode_area=n`. Multiple filters are `AND`'ed, i.e. each additional filter narrows the result set.\n\nA maximum of **10** terms are allowed across all filters.\n\n## Biases\n\nYou can boost certain addresses results that match specific address criteria. All bias searches are prefixed with `bias_`.\n\nBiasing (unlike filtering) also allow unmatched addresses to appear with lower precedence.\n\nFor instance, can boost addresses with postcode areas `SW` and `SE` by appending `bias_postcode_area=SW,SE`.\n\nNo bias effect applies to bias terms that are invalid. e.g. `bias_postcode=SW1A2AAA`\n\nYou may scope using multiple terms for the same bias with a comma separated list of terms. E.g. Restrict results to `E1`, `E2` and `E3` outward codes: <code>bias_postcode_outward=e1,e2,e3</code>.\n\nAll biases can accept multiple terms unless stated otherwise below.\n\nA combined maximum of **5** terms are allowed across all biases.\n\n## Suggestion Format\n\nThe suggestion format is prone to change over time. Attempts to parse the suggestion may result in your integration breaking. Instead use the suggestion as-is.\n\n## Rate Limiting\n\nYou can make up to 3000 requests to the autocomplete API within a 5 minute span. The HTTP Header contains information on your current rate limit.\n\n| Header                  | Description                                                                            |\n| ----------------------- | -------------------------------------------------------------------------------------- |\n| `X-RateLimit-Limit`     | The maximum number of requests that can be made in 5 minutes                           |\n| `X-RateLimit-Remaining` | The remaining requests within the current rate limit window                            |\n| `X-RateLimit-Reset`     | The time when the rate limit window resets in Unix Time (seconds) or UTC Epoch seconds |\n\n## Pricing\n\nThis API currently does not affect your balance. However, resolving a suggestion into a full address requires a paid request.\n\nPlease note, this API is not intended as a standalone free resource. Integrations that consistently make autocomplete requests without a paid request to resolve an address may be disrupted via tightened rate limits. Continued misuse will result in account suspension.\n"
  provider: ideal_postcodes
  method: GET
  path: "/autocomplete/addresses"
  encoding: json
  input: {
    type: "object"
    properties: {
      api_key: {
        type: "string"
        description: "Your API Key. Typically beings `ak_`.\n\nAvailable from your dashboard\n"
      }
      bias_country: {
        type: "string"
        description: "Bias by country. Possible values are England, Scotland, Wales, Northern Ireland, Jersey, Guernsey and Isle of Man."
      }
      bias_ip: {
        type: "string"
        description: "Biases search based on approximate geolocation of IP address.\nSet `bias_ip=true` to enable."
        enum: ["true"]
      }
      bias_lonlat: {
        type: "string"
        description: "Bias search to a geospatial circle determined by an origin and radius in meters. Max radius is `50000`.  Uses the format bias_lonlat=[longitude],[latitude],[radius in metres] Only one geospatial bias may be provided"
      }
      bias_post_town: {
        type: "string"
        description: "Bias by town."
      }
      bias_postcode: {
        type: "string"
        description: "Bias by postcode. Can be combined with query to perform a postcode + building number/name search."
      }
      bias_postcode_area: {
        type: "string"
        description: "Bias by postcode area, the first one or two non-numeric characters of a postcode."
      }
      bias_postcode_outward: {
        type: "string"
        description: "Bias by outward code"
      }
      bias_postcode_sector: {
        type: "string"
        description: "Bias by postcode sector, the outward code plus first numeric of the inward code."
      }
      bias_thoroughfare: {
        type: "string"
        description: "Bias by street name."
      }
      box: {
        type: "string"
        description: "Restrict search to a geospatial box determined by the \"top-left\" and \"bottom-right\" gelocations.   Only one geospatial box can be provided."
      }
      context: {
        type: "string"
        description: "Limits search results within a geographical boundary or country."
      }
      country: {
        type: "string"
        description: "Filter by country. Possible values are England, Scotland, Wales, Northern Ireland, Jersey, Guernsey and Isle of Man."
      }
      limit: {
        type: "integer"
        format: "int32"
        description: "Specifies the maximum number of suggestions to retrieve.\n\nBy default the limit is 10, unless a postcode is queried (then all addresses at that postcode will be returned). Limit can be shortened to `l=`\n"
      }
      post_town: {
        type: "string"
        description: "Filter by town. "
      }
      postcode: {
        type: "string"
        description: "Filter by postcode. Can be combined with query to perform a postcode + building number/name search."
      }
      postcode_area: {
        type: "string"
        description: "Filter by postcode. Can be combined with query to perform a postcode + building number/name search."
      }
      postcode_outward: {
        type: "string"
        description: "Filter by outward code."
      }
      postcode_sector: {
        type: "string"
        description: "Filter by postcode sector, the outward code plus first numeric of the inward code. "
      }
      postcode_type: {
        type: "string"
        description: "Filter by Postcode Type. Useful for separating organisational and residential addresses"
      }
      query: {
        type: "string"
      }
      su_organisation_indicator: {
        type: "string"
        description: "Filter by Organisation Indicator. Useful for separating organisational and residential addresses"
      }
      uprn: {
        type: "integer"
        description: "Filters by UPRN. Does not accept comma separated terms. Only a single term is permitted"
      }
    }
    additionalProperties: false
  }
  output: {
    type: "object"
    required: ["code", "message", "result"]
    properties: {
      code: {
        type: "integer"
        format: "int32"
        enum: [2000]
      }
      message: {
        type: "string"
        enum: ["Success"]
      }
      result: {
        type: "object"
        required: ["hits"]
        properties: {
          hits: {
            type: "array"
            items: {
              type: "object"
            }
          }
        }
      }
    }
  }
}