{"openapi":"3.2.0","info":{"title":"US Zip Code Radius and Lookup API","description":"U.S. ZIP code lookup, radius search, and distance API for fast and accurate geolocation. Instantly retrieve ZIP code details, find nearby ZIPs within a radius, calculate distances between ZIP codes, autocomplete ZIP inputs, and map cities to ZIPs. Designed for delivery zones, store locators, logistics platforms, and location-based services.","version":"1.0.0"},"servers":[{"url":"https://wxtfd.jojapi.net"}],"security":[{"ApiKeyAuth":[]}],"tags":[{"name":"US Zip Code Radius & Lookup API"}],"x-agent-commerce":{"catalog_url":"https://wxtfd.jojapi.net/_jojapi/agent/plans","discovery_url":"https://wxtfd.jojapi.net/.well-known/x402","directory_url":"https://agents.jojapi.net/apis/us-zip-code-radius-and-lookup-api","docs":"https://docs.jojapi.com/consumers/agents"},"paths":{"/zipcode/v1/distance":{"get":{"operationId":"get_zipcode_v1_distance","summary":"Distance Between Two Zip Codes","description":"Computes the geographical distance between two specified US zip codes, returning the value in either miles or kilometers.","tags":["US Zip Code Radius & Lookup API"],"responses":{"200":{"description":"Successful response with the calculated distance, or empty result if zip codes not found.","content":{"application/json":{"schema":{"type":"object","description":"Successful response wrapper with metadata for distance calculation.","properties":{"metadata":{"type":"object","properties":{"timestamp":{"type":"string","format":"date-time"}},"required":["timestamp"]},"success":{"type":"boolean","description":"Indicates the API call succeeded."},"found":{"type":"boolean","description":"Indicates whether the requested data was found."},"data":{"type":"object","description":"Represents the calculated distance between two zip codes.","properties":{"distance":{"type":"number","format":"float","description":"The calculated distance between the two zip codes.","minimum":-3.402823669209385e+38,"maximum":3.402823669209385e+38},"unit":{"type":"string","enum":["mi","km"],"description":"The unit of measurement for the distance (miles or kilometers)."}},"required":["distance","unit"]}},"required":["metadata","success","found","data"]},"examples":{"Example_1":{"summary":"Example_1","value":{"metadata":{"timestamp":""},"success":true,"found":true,"data":{"distance":347.5,"unit":"mi"}}}}}}},"400":{"description":"Invalid request, e.g., missing 'from' or 'to' zip codes.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"A human-readable message describing the error."},"status":{"type":"integer","format":"int32","description":"The HTTP status code.","minimum":-2147483648,"maximum":2147483647},"timestamp":{"type":"string","format":"date-time","description":"The time the error occurred."}},"required":["message","status","timestamp"]},"examples":{"Example_1":{"summary":"Example_1","value":{"message":"","status":0,"timestamp":""}}}}}},"500":{"description":"Internal Server Error.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"A human-readable message describing the error."},"status":{"type":"integer","format":"int32","description":"The HTTP status code.","minimum":-2147483648,"maximum":2147483647},"timestamp":{"type":"string","format":"date-time","description":"The time the error occurred."}},"required":["message","status","timestamp"]},"examples":{"Example_1":{"summary":"Example_1","value":{"message":"","status":0,"timestamp":""}}}}}}},"parameters":[{"name":"from","in":"query","description":"The originating US zip code.","required":true,"schema":{"type":"string","example":"90210"}},{"name":"to","in":"query","description":"The destination US zip code.","required":true,"schema":{"type":"string","example":"94107"}},{"name":"unit","in":"query","description":"The unit of measurement for the distance. Defaults to 'mi' (miles) if not specified.","required":false,"schema":{"type":"string","enum":["mi","km"],"default":"mi"}}]}},"/zipcode/v1/radius":{"get":{"operationId":"get_zipcode_v1_radius","summary":"Zip Codes In Radius","description":"Retrieves a list of US zip codes that fall within a specified radius (in miles or kilometers) of a given origin US zip code.","tags":["US Zip Code Radius & Lookup API"],"responses":{"200":{"description":"Successful response with a list of zip codes within the radius, or empty array if origin not found or no results.","content":{"application/json":{"schema":{"type":"object","description":"Successful response wrapper with metadata for radius search.","properties":{"metadata":{"type":"object","properties":{"timestamp":{"type":"string","format":"date-time"}},"required":["timestamp"]},"success":{"type":"boolean","description":"Indicates the API call succeeded."},"found":{"type":"boolean","description":"Indicates whether the requested data was found."},"data":{"type":"object","description":"Represents the response for a zip code radius search.","properties":{"originZipcode":{"type":"string","description":"The zip code used as the center of the radius search."},"radius":{"type":"number","format":"float","description":"The radius used for the search, in the unit specified.","minimum":-3.402823669209385e+38,"maximum":3.402823669209385e+38},"unit":{"type":"string","enum":["mi","km"],"description":"The unit of measurement for the radius and distances."},"zipcodes":{"type":"array","description":"A list of zip codes found within the specified radius.","items":{"type":"object","description":"Represents a zip code found within a specified radius, including its distance from the origin.","properties":{"city":{"type":"string","description":"The city name associated with the zip code."},"zipcode":{"type":"string","description":"The zip code identifier."},"distance":{"type":"number","format":"float","description":"The distance from the origin zip code, in the unit specified in the request.","minimum":-3.402823669209385e+38,"maximum":3.402823669209385e+38}},"required":["city","zipcode","distance"]}}},"required":["originZipcode","radius","unit","zipcodes"]}},"required":["metadata","success","found","data"]},"examples":{"Example_1":{"summary":"Example_1","value":{"metadata":{"timestamp":""},"success":true,"found":true,"data":{"originZipcode":"90210","radius":10,"unit":"mi","zipcodes":[{"city":"Santa Monica","zipcode":"90401","distance":5.25}]}}}}}}},"400":{"description":"Invalid request, e.g., missing parameters, invalid radius, or radius exceeds limit.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"A human-readable message describing the error."},"status":{"type":"integer","format":"int32","description":"The HTTP status code.","minimum":-2147483648,"maximum":2147483647},"timestamp":{"type":"string","format":"date-time","description":"The time the error occurred."}},"required":["message","status","timestamp"]},"examples":{"Example_1":{"summary":"Example_1","value":{"message":"","status":0,"timestamp":""}}}}}},"500":{"description":"Internal Server Error.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"A human-readable message describing the error."},"status":{"type":"integer","format":"int32","description":"The HTTP status code.","minimum":-2147483648,"maximum":2147483647},"timestamp":{"type":"string","format":"date-time","description":"The time the error occurred."}},"required":["message","status","timestamp"]},"examples":{"Example_1":{"summary":"Example_1","value":{"message":"","status":0,"timestamp":""}}}}}}},"parameters":[{"name":"zipcode","in":"query","description":"The origin US zip code for the radius search.","required":true,"schema":{"type":"string","example":"90210"}},{"name":"radius","in":"query","description":"The radius for the search. Must be a positive number. Max 200 mi or 320 km.","required":true,"schema":{"type":"number","example":10}},{"name":"unit","in":"query","description":"The unit of measurement for the radius. Defaults to 'mi' (miles).","required":false,"schema":{"type":"string","enum":["mi","km"],"default":"mi"}}]}},"/zipcode/v1/by-city":{"get":{"operationId":"get_zipcode_v1_by_city","summary":"Zip Codes By State & City","description":"Retrieves a list of all US zip codes associated with a given city name and a two-letter state abbreviation.","tags":["US Zip Code Radius & Lookup API"],"responses":{"200":{"description":"Successful response with a list of zip codes for the city and state, or empty array if not found.","content":{"application/json":{"schema":{"type":"object","description":"Successful response wrapper with metadata for city/state lookup.","properties":{"metadata":{"type":"object","properties":{"timestamp":{"type":"string","format":"date-time"}},"required":["timestamp"]},"success":{"type":"boolean","description":"Indicates the API call succeeded."},"found":{"type":"boolean","description":"Indicates whether the requested data was found."},"data":{"type":"object","description":"Represents the data structure for a city/state to zip codes lookup.","properties":{"queriedCity":{"type":"string","description":"The city name that was queried."},"queriedState":{"type":"string","description":"The full state name that was queried."},"queriedStateAbbreviation":{"type":"string","description":"The two-letter state abbreviation that was queried."},"zipcodes":{"type":"array","description":"A list of zip codes found within the queried city and state.","items":{"type":"object","description":"Represents a specific zip code within a city context.","properties":{"city":{"type":"string","description":"The name of the city associated with this zip code entry. Note that for a given query, this will typically be the same as queriedCity but is included for structural consistency if a zip code can span multiple \"place names\" that roll up to a single queried city."},"zipcode":{"type":"string","description":"The zip code identifier."}},"required":["city","zipcode"]}}},"required":["queriedCity","queriedState","queriedStateAbbreviation","zipcodes"]}},"required":["metadata","success","found","data"]},"examples":{"Example_1":{"summary":"Example_1","value":{"metadata":{"timestamp":""},"success":true,"found":true,"data":{"queriedCity":"Springfield","queriedState":"Illinois","queriedStateAbbreviation":"IL","zipcodes":[{"city":"Springfield","zipcode":"62701"}]}}}}}}},"400":{"description":"Invalid request, e.g., missing city or state, or invalid state format.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"A human-readable message describing the error."},"status":{"type":"integer","format":"int32","description":"The HTTP status code.","minimum":-2147483648,"maximum":2147483647},"timestamp":{"type":"string","format":"date-time","description":"The time the error occurred."}},"required":["message","status","timestamp"]},"examples":{"Example_1":{"summary":"Example_1","value":{"message":"","status":0,"timestamp":""}}}}}},"500":{"description":"Internal Server Error.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"A human-readable message describing the error."},"status":{"type":"integer","format":"int32","description":"The HTTP status code.","minimum":-2147483648,"maximum":2147483647},"timestamp":{"type":"string","format":"date-time","description":"The time the error occurred."}},"required":["message","status","timestamp"]},"examples":{"Example_1":{"summary":"Example_1","value":{"message":"","status":0,"timestamp":""}}}}}}},"parameters":[{"name":"state","in":"query","description":"The two-letter US state abbreviation (e.g., CA, IL, NY).","required":true,"schema":{"type":"string","example":"IL"}},{"name":"city","in":"query","description":"The name of the city.","required":true,"schema":{"type":"string","example":"Springfield"}}]}},"/zipcode/v1/autocomplete":{"get":{"operationId":"get_zipcode_v1_autocomplete","summary":"Autocomplete Suggestions (City and Zip Code)","description":"Provides a list of US zip code suggestions based on a partial query string. Useful for implementing type-ahead features.","tags":["US Zip Code Radius & Lookup API"],"responses":{"200":{"description":"Successful response with a list of suggestions (can be empty if no matches).","content":{"application/json":{"schema":{"type":"object","description":"Successful response wrapper with metadata for autocomplete suggestions.","properties":{"metadata":{"type":"object","properties":{"timestamp":{"type":"string","format":"date-time"}},"required":["timestamp"]},"success":{"type":"boolean","description":"Indicates the API call succeeded."},"found":{"type":"boolean","description":"Indicates whether suggestions were found."},"data":{"type":"object","description":"Represents the response for a zip code autocomplete query.","properties":{"suggestions":{"type":"array","description":"A list of zip code suggestions based on the query.","items":{"type":"object","description":"Represents a single zip code suggestion for autocomplete.","properties":{"zipcode":{"type":"string","description":"The suggested zip code."},"city":{"type":"string","description":"The city associated with the suggested zip code."},"state":{"type":"string","description":"The full state name for the suggestion."},"stateAbbreviation":{"type":"string","description":"The two-letter state abbreviation for the suggestion."}},"required":["zipcode","city","state","stateAbbreviation"]}}},"required":["suggestions"]}},"required":["metadata","success","found","data"]},"examples":{"Example_1":{"summary":"Example_1","value":{"metadata":{"timestamp":""},"success":true,"found":true,"data":{"suggestions":[{"zipcode":"90210","city":"Beverly Hills","state":"California","stateAbbreviation":"CA"}]}}}}}}},"400":{"description":"Invalid request, e.g., missing query parameter or query too short.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"A human-readable message describing the error."},"status":{"type":"integer","format":"int32","description":"The HTTP status code.","minimum":-2147483648,"maximum":2147483647},"timestamp":{"type":"string","format":"date-time","description":"The time the error occurred."}},"required":["message","status","timestamp"]},"examples":{"Example_1":{"summary":"Example_1","value":{"message":"","status":0,"timestamp":""}}}}}},"500":{"description":"Internal Server Error.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"A human-readable message describing the error."},"status":{"type":"integer","format":"int32","description":"The HTTP status code.","minimum":-2147483648,"maximum":2147483647},"timestamp":{"type":"string","format":"date-time","description":"The time the error occurred."}},"required":["message","status","timestamp"]},"examples":{"Example_1":{"summary":"Example_1","value":{"message":"","status":0,"timestamp":""}}}}}}},"parameters":[{"name":"q","in":"query","description":"The partial query string for zip code or city name. Minimum 2 characters.","required":true,"schema":{"type":"string","example":"902"}}]}},"/zipcode/v1/lookup/{zip}":{"get":{"operationId":"get_zipcode_v1_lookup_zip","summary":"US Zip Code Info","description":"Retrieves city and state information associated with a given US zip code.","tags":["US Zip Code Radius & Lookup API"],"responses":{"200":{"description":"Successful response with zip code information, or empty result if not found.","content":{"application/json":{"schema":{"type":"object","description":"Successful response wrapper with metadata for zip code lookup.","properties":{"metadata":{"type":"object","properties":{"timestamp":{"type":"string","format":"date-time"}},"required":["timestamp"]},"success":{"type":"boolean","description":"Indicates the API call succeeded."},"found":{"type":"boolean","description":"Indicates whether the requested data was found."},"data":{"type":"object","description":"Represents the US-specific data structure for a zip code lookup.","properties":{"zipcode":{"type":"string","description":"The requested zip code."},"cities":{"type":"array","description":"A list of cities and their state information associated with the zip code.","items":{"type":"object","description":"Represents US-specific place details.","properties":{"city":{"type":"string","description":"The name of the city."},"state":{"type":"string","description":"The full name of the state."},"stateAbbreviation":{"type":"string","description":"The two-letter abbreviation for the state."}},"required":["city","state","stateAbbreviation"]}}},"required":["zipcode","cities"]}},"required":["metadata","success","found","data"]},"examples":{"Example_1":{"summary":"Example_1","value":{"metadata":{"timestamp":""},"success":true,"found":true,"data":{"zipcode":"90210","cities":[{"city":"Beverly Hills","state":"California","stateAbbreviation":"CA"}]}}}}}}},"400":{"description":"Invalid request, e.g., missing zip code.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"A human-readable message describing the error."},"status":{"type":"integer","format":"int32","description":"The HTTP status code.","minimum":-2147483648,"maximum":2147483647},"timestamp":{"type":"string","format":"date-time","description":"The time the error occurred."}},"required":["message","status","timestamp"]},"examples":{"Example_1":{"summary":"Example_1","value":{"message":"","status":0,"timestamp":""}}}}}},"500":{"description":"Internal Server Error.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"A human-readable message describing the error."},"status":{"type":"integer","format":"int32","description":"The HTTP status code.","minimum":-2147483648,"maximum":2147483647},"timestamp":{"type":"string","format":"date-time","description":"The time the error occurred."}},"required":["message","status","timestamp"]},"examples":{"Example_1":{"summary":"Example_1","value":{"message":"","status":0,"timestamp":""}}}}}}},"parameters":[{"name":"zip","in":"path","required":true,"schema":{"type":"string","example":"90102"}}]}}},"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-JoJAPI-Key","description":"Your JoJ API key."}}}}