{"openapi":"3.1.0","info":{"title":"x402 Agent Data API","description":"Pay-per-call data for AI agents: weather, geocoding, reverse geocoding, public holidays, phone validation and FX rates. USDC on Base via x402.","version":"3.0.0"},"servers":[{"url":"https://x402-weather.onrender.com"}],"paths":{"/weather":{"get":{"summary":"Current weather (paid)","operationId":"weather_weather_get","parameters":[{"name":"city","in":"query","required":true,"schema":{"type":"string","minLength":1,"maxLength":100,"title":"City"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{},"example":{"location":{"name":"Bloemfontein","country":"South Africa","country_code":"ZA","lat":-29.1211,"lon":26.214,"elevation_m":1396,"timezone":"Africa/Johannesburg","local_time":"2026-11-06T09:00:00+02:00"},"conditions":{"summary":"Clear sky","symbol_code":"clearsky_day","is_day":true},"thermal":{"temp_c":22.4,"feels_like_c":22.4,"dew_point_c":5.5,"uv_index_clear_sky":7.3,"next_6h_min_c":23.8,"next_6h_max_c":27.3},"atmosphere":{"humidity_pct":33.2,"pressure_hpa":1011.6,"cloud_cover_pct":0,"fog_pct":0},"precipitation":{"next_1h_mm":0,"next_6h_mm":0},"wind":{"speed_kph":12.2,"speed_ms":3.4,"direction_degrees":294,"direction_compass":"WNW"},"valid_time_utc":"2026-11-06T07:00:00Z","model_updated_utc":"2026-11-06T07:25:38Z","attribution":{"weather":"Data from MET Norway (api.met.no), CC BY 4.0","locations":"Location data from GeoNames (geonames.org), CC BY 4.0","license":"https://creativecommons.org/licenses/by/4.0/"}}}}},"402":{"description":"Payment required — see PAYMENT-REQUIRED header"},"404":{"description":"Not found (not charged)"},"400":{"description":"Invalid input (not charged)"},"502":{"description":"Upstream provider error (not charged)"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/geocode":{"get":{"summary":"Place name to coordinates (paid)","operationId":"geocode_geocode_get","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","minLength":1,"maxLength":100,"title":"Q"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":10,"minimum":1,"default":5,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{},"example":{"query":"Bloemfontein","results":[{"name":"Bloemfontein","country":"South Africa","country_code":"ZA","lat":-29.12107,"lon":26.214,"population":556637,"timezone":"Africa/Johannesburg","geonames_id":1018725}],"attribution":{"source":"GeoNames (geonames.org), CC BY 4.0","license":"https://creativecommons.org/licenses/by/4.0/"}}}}},"402":{"description":"Payment required — see PAYMENT-REQUIRED header"},"404":{"description":"Not found (not charged)"},"400":{"description":"Invalid input (not charged)"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/reverse-geocode":{"get":{"summary":"Coordinates to nearest city (paid)","operationId":"reverse_geocode_reverse_geocode_get","parameters":[{"name":"lat","in":"query","required":true,"schema":{"type":"number","maximum":90,"minimum":-90,"title":"Lat"}},{"name":"lon","in":"query","required":true,"schema":{"type":"number","maximum":180,"minimum":-180,"title":"Lon"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{},"example":{"query":{"lat":-29.12,"lon":26.21},"nearest":{"name":"Bloemfontein","country":"South Africa","country_code":"ZA","lat":-29.12107,"lon":26.214,"population":556637,"timezone":"Africa/Johannesburg","geonames_id":1018725,"distance_km":0.42},"attribution":{"source":"GeoNames (geonames.org), CC BY 4.0","license":"https://creativecommons.org/licenses/by/4.0/"}}}}},"402":{"description":"Payment required — see PAYMENT-REQUIRED header"},"404":{"description":"Not found (not charged)"},"400":{"description":"Invalid input (not charged)"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/holidays":{"get":{"summary":"Public holidays by country (paid)","operationId":"holidays_endpoint_holidays_get","parameters":[{"name":"country","in":"query","required":true,"schema":{"type":"string","minLength":2,"maxLength":60,"title":"Country"}},{"name":"year","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","maximum":2100,"minimum":1950},{"type":"null"}],"title":"Year"}},{"name":"date","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Date"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{},"example":{"country_code":"ZA","country":"South Africa","year":2026,"count":2,"holidays":[{"date":"2026-01-01","name":"New Year's Day","weekday":"Thursday"},{"date":"2026-03-21","name":"Human Rights Day","weekday":"Saturday"}],"attribution":{"source":"python-holidays (MIT licence)"}}}}},"402":{"description":"Payment required — see PAYMENT-REQUIRED header"},"404":{"description":"Not found (not charged)"},"400":{"description":"Invalid input (not charged)"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/phone/validate":{"get":{"summary":"Validate and format a phone number (paid)","operationId":"phone_validate_phone_validate_get","parameters":[{"name":"number","in":"query","required":true,"schema":{"type":"string","minLength":3,"maxLength":40,"title":"Number"}},{"name":"region","in":"query","required":false,"schema":{"anyOf":[{"type":"string","minLength":2,"maxLength":2},{"type":"null"}],"title":"Region"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{},"example":{"input":"+27 21 123 4567","valid":true,"possible":true,"type":"fixed_line","e164":"+27211234567","international":"+27 21 123 4567","national":"021 123 4567","country_code":"ZA","calling_code":27,"timezones":["Africa/Johannesburg"],"attribution":{"source":"Google libphonenumber metadata (Apache 2.0)"}}}}},"402":{"description":"Payment required — see PAYMENT-REQUIRED header"},"404":{"description":"Not found (not charged)"},"400":{"description":"Invalid input (not charged)"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/fx":{"get":{"summary":"Currency exchange rates (paid)","operationId":"fx_fx_get","parameters":[{"name":"base","in":"query","required":false,"schema":{"type":"string","minLength":3,"maxLength":3,"default":"USD","title":"Base"}},{"name":"symbols","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"title":"Symbols"}},{"name":"amount","in":"query","required":false,"schema":{"anyOf":[{"type":"number","exclusiveMinimum":0},{"type":"null"}],"title":"Amount"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{},"example":{"base":"USD","date":"2026-11-05","amount":100,"rates":{"ZAR":17.6512,"EUR":0.9256},"converted":{"ZAR":1765.12,"EUR":92.56},"attribution":{"source":"European Central Bank (ECB) euro foreign exchange reference rates","free_source":"This information is available free of charge from the ECB at https://www.ecb.europa.eu/stats/policy_and_exchange_rates/euro_reference_exchange_rates/html/index.en.html","modification":"Rates for bases other than EUR are calculated by this API from the ECB euro rates.","note":"Reference rates for information only, not trading quotes."}}}}},"402":{"description":"Payment required — see PAYMENT-REQUIRED header"},"404":{"description":"Not found (not charged)"},"400":{"description":"Invalid input (not charged)"},"502":{"description":"Upstream provider error (not charged)"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}}}