openapi: 3.0.1 info: title: us-reverse-geo version: '0.23' description: This api runs Smarty's reverse geocoding algorithms to convert latitudinal and longitudinal coordinates into the closest street addresses at lightning speed! contact: url: 'https://www.smarty.com/contact/support' email: support@smarty.com name: Smarty Support termsOfService: 'https://www.smarty.com/legal/terms-of-service' license: url: 'https://www.smarty.com/legal/terms-of-service' name: Smarty License servers: - url: us-reverse-geo.api.smarty.com externalDocs: description: "Extensive documentation for the US Reverse Geocoding API" url: https://www.smarty.com/docs/cloud/us-reverse-geo-api tags: - name: reverse-geo description: Operation invlovling reverse geocoding paths: /lookup: get: summary: Convert Coordinates to Nearest Addresses tags: - reverse-geo responses: '200': $ref: '#/components/responses/ReverseGeoValidResponse' '400': description: 'Bad Request, The request body was blank or otherwise malformed.' '401': description: 'Unauthorized, The credentials were provided incorrectly or did not match any existing, active credentials.' '402': description: 'Payment Required, There is no active subscription for the account associated with the credentials submitted with the request.' '422': description: 'Unprocessable Entity (Unsuitable Parameters), Returns errors describing what needs to be corrected.' '429': description: 'Too Many Requests, When using public embedded key authentication, we restrict the number of requests coming from a given source over too short of a time. If you use embedded key authentication, you can avoid this error by adding your IP address as an authorized host for the embedded key in question.' operationId: get-street-address parameters: - schema: type: string in: header name: Host required: true description: 'The Host request header field specifies the internet host and port number of the resource being requested. Note: Most HTTP clients such as the browser, or programming language HTTP libraries will add this header automatically.' - schema: type: string in: header name: Referer required: false description: 'The Referer is required when an embedded key is used for authentication. Its value is in the form of a URL, where the host component must match a host value assigned to your embedded key. Note: Some HTTP clients such as a browser, or programming language HTTP libraries will add this header automatically. However some interfaces such as cURL do not, so you may need to add it manually.' - schema: type: number in: query name: latitude required: true description: 'Latitude portion of the coordinate. The latitude must be specified as a decimal between -90.0 and 90.0' - schema: type: number in: query name: longitude required: true description: 'Longitude portion of the coordinate. The longitude must be specified as a decimal between -180.0 and 180.0' - schema: type: string in: query name: source required: false description: 'Includes all results from alternate data sources. Allowed values are: all - will include non-postal addresses in the results; postal - will limit the results to postal addresses only. If this parameter is used, an additional field named soruce will be returned for each result. Default: postal' description: This api runs Smarty's reverse geocoding algorithms to convert latitudinal and longitudinal coordinates into the closest street addresses at lightning speed! Enter your auth-id and auth-token or just a Smarty embedded-key along with your coordinates and you are off! security: - auth-id: [ ] auth-token: [ ] - embedded-key: [ ] parameters: [ ] components: schemas: Result: title: Result type: array maxLength: 10 items: type: object properties: coordinate: $ref: '#/components/schemas/Coordinate' description: Coordinate object containing basic coordinate information distance: type: number examples: - 34.95276 description: The distance in meters of this address to the input latitude/longitude values. address: $ref: '#/components/schemas/Address' description: Address object containing basic address information required: - address - coordinate Coordinate: type: object examples: - latitude: 40.202583 longitude: -111.62196 accuracy: Rooftop license: 1 title: Coordinate description: Object containing basic coordinate information properties: latitude: type: number description: |- Type: Decimal Info: The latitude value of this address. longitude: type: number description: |- Type: Decimal Info: The longitude value of this address. accuracy: type: string maxLength: 18 description: |- Type: varchar(18) Info: Indicates the accuracy of the latitude and longitude values. Unknown — Coordinates not known. Reasons could include: lat/lon coordinates not available. Zip5 — Accurate to a 5-digit ZIP Code level (least accurate) Zip6 — Accurate to a 6-digit ZIP Code level Zip7 — Accurate to a 7-digit ZIP Code level Zip8 — Accurate to an 8-digit ZIP Code level Zip9 — Accurate to a 9-digit ZIP Code level Parcel — Accurate to the centroid of a property parcel. Rooftop — Accurate to the rooftop of a structure for this address. Note: Concerning addresses for which the ZIP9 accuracy is not available, the ZIP# accuracy is interpolated based on neighboring addresses. Thus, ZIP7 is an average of all the lat/long coordinates of nearby ZIP Codes that share those first 7 digits. license: type: integer description: |- Type: int Info: The license ID for the geographic coordinate returned. See the licensing table at https://www.smarty.com/docs/cloud/us-reverse-geo-api for more details required: - latitude - longitude - license Address: type: object examples: - street: 1476 Sandhill Rd city: Orem state_abbreviation: UT zipcode: '84058' title: Address description: Object containing basic address information properties: street: type: string maxLength: 64 description: varchar(64) The street name of this address. city: type: string maxLength: 64 description: varchar(64) The city name of this address. state_abbreviation: type: string maxLength: 2 description: varchar(2) The state abbreviation of this address. zipcode: type: string maxLength: 5 description: varchar(5) The 5-digit ZIP Code of this address. source: type: string maxLength: 6 description: This field is only returned if the request contained the source parameter. When it is returned, it indicates the data source for this address. Postal - the address is deliverable by the USPS. Other - the address was obtained from an alternate source (non-postal). smarty_key: type: string maxLength: 10 description: Smarty's unique identifier for an address required: - Street - city - state_abbreviation - zipcode - smarty_key securitySchemes: auth-id: name: auth-id type: apiKey in: query description: URL-encoded ID generated with an associated token in the users Smarty account auth-token: name: auth-token type: apiKey in: query description: Authentication token generated with an associated URL-encoded ID in the users Smarty account embedded-key: name: key type: apiKey in: query description: Embedded key are associated with one or more hostnames and/or IP addresses which you specify. Each of the hostnames (indicated by the 'Referer' header or 'Origin' header) will be granted rate-limited permission to call the API with the associated embedded key. responses: ReverseGeoValidResponse: description: 'Valid reverse geocoding response containing the results of the search. Each object in the results list will contain an Address object, Coordinate object, and an optional distance field. The distance field is left blank where there is an exact match.' content: application/json: schema: type: object properties: results: $ref: '#/components/schemas/Result' description: 'The array of result objects. Each object contains a coordinate object, a distance, and an address object.' required: - results