action ideal_postcodes_addresses {
  label: "Extract Addresses"
  description: "Extract a list of complete addresses that match the query ordered by relevance score. This query accepts an optional limit and page query (defaults to 10 and 0 respectively).\n\nIf a valid postcode is passed as the query string, the entire address list for that postcode is passed as a result. Note, in these cases, limit and page parameters are ignored.\n\nThis API is designed as a multi-purpose tool for generating address lists, cleansing and wholesale data extraction according to specific parameters.\n\nFor address autocomplete, see our address finder API - which is designed for speed and address completion.\n\n## Reverse Geocoding\n\nReturn a list of addresses around a point using the lon= and lat= querystring arguments. Addresses will be sorted in order of distance to the point. The search radius is 100m.\n\n## Filters\n\nYou can strictly narrow your result by adding filters to your query string which correspond with an address attribute.\n\nFor 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\nMultiple filters 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 combined maximum of 5 terms are allowed across all filters.\n\n## Biases\n\nYou can boost certain addresses results that correspond with a certain address attribute. All bias searches are prefixed with `bias_`.\n\nBiased searches, unlike filtered searches, also allow unmatched addresses to appear . These will rank lower.\n\nFor instance, you can boost addresses with postcode areas `SW` and `SE` by appending `bias_postcode_area=SW,SE`.\n\nIf a bias term is invalid, e.g. `bias_postcode=SW1A2AAA` no bias effect is applied.\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: `bias_postcode_outward=e1,e2,e3`.\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## Search by Postcode and Building Name or Number\n\nSearch by postcode and building attribute with the postcode filter and query argument. E.g. For \"SW1A 2AA Prime Minister\" `/v1/addresses?postcode=sw1a2aa&q=prime minister`.\n\nThe advantage of using filters is a postcode mismatch does not result in a lookup as no results are returned.\n\n#### Search By UPRN\n\nSearch by UPRN using the `uprn` filter and excluding the query argument. E.g. `/v1/addresses?uprn=100`.\n\n## Testing\n\n- **ID1 1QD** Returns a successful query response `2000`\n- **ID1 KFA** Returns an empty query response `2000`\n- **ID1 CLIP** Returns \"no lookups remaining\" error `4020`\n- **ID1 CHOP** Returns \"daily (or individual) lookup limit breached\" error `4021`\n\nTest request undergo the usual authentication and restriction rules. This is to help surface any issues that occur during implementation and does not cost you a lookup.\n"
  provider: ideal_postcodes
  method: GET
  path: "/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_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."
      }
      country: {
        type: "string"
        description: "Filter by country. Possible values are England, Scotland, Wales, Northern Ireland, Jersey, Guernsey and Isle of Man."
      }
      filter: {
        type: "string"
        description: "Comma separated whitelist of address elements to return. \n\nE.g. `filter=line_1,line_2,line_3` returns only `line_1`, `line_2` and `line_3` address elements in your response\n"
      }
      lat: {
        type: "number"
        format: "float"
        description: "Latitude query for reverse geocoding.\n\nAn accompanying longitude (lon=) query must be submitted for a valid reverse geocode query.\n"
      }
      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"
      }
      lon: {
        type: "number"
        format: "float"
        description: "Longitude query for reverse geocoding.\n\nAn accompanying latitude (lat=) query must be submitted for a valid reverse geocode query.\n"
      }
      page: {
        type: "integer"
        format: "int32"
        description: "0 indexed indicator of the page of results to receive. Virtually all postcode results are returned on page 0. \n\nA small number of Multiple Residence postcodes may need pagination (i.e. have more than 100 premises).\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"
      }
    }
    required: ["api_key"]
    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", "limit", "page", "total"]
        properties: {
          hits: {
            type: "array"
            description: "List of matching addresses\n"
            items: {
              type: "object"
            }
          }
          limit: {
            type: "integer"
            format: "int32"
          }
          page: {
            type: "integer"
            format: "int32"
          }
          total: {
            type: "integer"
            format: "int32"
          }
        }
      }
    }
  }
}