"""
Geocoding
Code or decode a postal address to or from geographical coordinates.
"""
name = "address/geocoding"
version = "3.1.2"

"""
Geocode address

Geocode a postal address into geographical coordinates (latitude and longitude).
"""
usecase Geocode {
  input {
    query
    streetAddress
    addressLocality
    addressRegion
    addressCountry
    postalCode
  }

  result {
    latitude!
    longitude!
  }

  error {
    title!
    detail
  }


  example UsingFreeformQuery {
    input {
      query = '1600 Amphitheatre Parkway, Mountain View, CA'
    }

    result {
      latitude = 37.423199,
      longitude = -122.084068
    }
  }

  example UsingFullAddress {
    input {
      streetAddress = '1600 Amphitheatre Parkway',
      addressLocality = 'Mountain View',
      addressRegion = 'California',
      addressCountry = 'USA',
      postalCode = '94043'
    }

    result {
      latitude = 37.423199,
      longitude = -122.084068
    }
  }

  example Failed {
    input {
      query = 'Hometown'
    }

    error {
      title = 'Bad request'
      detail = 'Missing or bad query'
    }
  }
}

"""
Reverse geocode

Decodes geographical coordinates (latitude and longitude) into a postal address.
"""
usecase ReverseGeocode {
  input {
    latitude!
    longitude!
  }

  result [{
    addressCountry
    addressRegion
    addressLocality
    streetAddress
    postalCode
    formattedAddress
  }]  

  error {
    title!
    detail
  }

  example Successful {
    input {
      latitude = 37.423199,
      longitude = -122.084068
    }

    result [{
      addressCountry = 'us',
      addressLocality = 'Mountain View',
      addressRegion = 'CA',
      formattedAddress = 'Amphitheatre Parkway, Mountain View, CA 94043, United States of America',
      postalCode = '94043',
      streetAddress = 'Amphitheatre Parkway',
    }]
  }

  example Failed {
    input {
      latitude = 720,
      longitude = 540
    }

    error {
      title = 'Bad request',
      detail = 'The provided coordinates in query are invalid, out of range, or not in the expected format'
    }
  }
}

"""
Query
Free-form query string to search for. For example, '1600 Amphitheatre Parkway, Mountain View, CA' or just 'Mountain View'
"""
field query

"""
Country
The country. For example, USA. You can also provide the two-letter ISO 3166-1 alpha-2 country code.
"""
field addressCountry

"""
Region
The region in which the locality is, and which is in the country. For example, California or another appropriate first-level Administrative division.
"""
field addressRegion

"""
Locality
The locality in which the street address is, and which is in the region. For example, Mountain View.
"""
field addressLocality

"""
Postal code
The postal code. For example, 94043.
"""
field postalCode

"""
Street address
The street address. For example, 1600 Amphitheatre Pkwy.
"""
field streetAddress

"""
Latitude
The latitude of a location. For example 37.42242 (WGS 84).
"""
field latitude

"""
Longitude
The longitude of a location. For example -122.08585 (WGS 84).
"""
field longitude

"""Formatted address
Address formatted as one string
"""
field formattedAddress

"""
Title
A short, human-readable summary of the problem type.
"""
field title

"""
Detail
A human-readable explanation specific to this occurrence of the problem.
"""
field detail