{"openapi":"3.1.0","info":{"title":"Satellite & GeoRisk x402 API","version":"1.0.0","description":"Agent-first paid geocoding, satellite imagery, and current multi-hazard location risk intelligence over x402 v2.","contact":{"email":"support@ipintel.ai"},"x-guidance":"Use POST /address-to-coordinates to convert an address or place name into coordinates. Use POST /coordinates-to-address to convert coordinates into an address. Use POST /satellite-observe to request satellite imagery for a location. Use POST /location-risk to inspect current nearby natural-hazard signals. All four operations accept JSON and require x402 payment before execution."},"servers":[{"url":"https://sat.ipintel.ai"}],"paths":{"/address-to-coordinates":{"post":{"operationId":"address_to_coordinates","summary":"Address to coordinates","description":"Convert an address, landmark, city, postcode, or place name into latitude and longitude.","tags":["Geocoding","Location"],"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.002"},"protocols":[{"x402":{}}]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"address":{"type":"string","minLength":3,"maxLength":500,"description":"Free-form place or postal address."},"country_code":{"type":"string","minLength":2,"maxLength":2,"description":"Optional ISO 3166-1 alpha-2 country filter."},"language":{"type":"string","minLength":2,"maxLength":12,"description":"Preferred response language, for example en or es."},"limit":{"type":"integer","minimum":1,"maximum":5,"default":1}},"required":["address"]},"example":{"address":"Eiffel Tower, Paris, France","country_code":"fr","language":"en","limit":1}}}},"responses":{"200":{"description":"Successful paid response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"ok":{"type":"boolean","const":true},"tool":{"type":"string","const":"address-to-coordinates"},"match_count":{"type":"integer","minimum":0},"results":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"formatted_address":{"type":"string"},"lat":{"type":"number"},"lon":{"type":"number"},"confidence":{"type":"number"},"country_code":{"type":"string"}},"required":["lat","lon"]}},"cached":{"type":"boolean"}},"required":["ok","tool","match_count","results"]}}}},"400":{"description":"Invalid request"},"402":{"description":"Payment Required","headers":{"PAYMENT-REQUIRED":{"description":"Base64-encoded x402 v2 payment challenge.","schema":{"type":"string"}}}},"413":{"description":"Request body exceeds 65,536 bytes"},"500":{"description":"Service or upstream provider failure"}}}},"/coordinates-to-address":{"post":{"operationId":"coordinates_to_address","summary":"Coordinates to address","description":"Convert latitude and longitude into a normalized address and location components.","tags":["Reverse Geocoding","Location"],"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.002"},"protocols":[{"x402":{}}]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"lat":{"type":"number","minimum":-90,"maximum":90},"lon":{"type":"number","minimum":-180,"maximum":180},"language":{"type":"string","minLength":2,"maxLength":12,"description":"Preferred response language."},"type":{"type":"string","enum":["country","state","city","postcode","street","amenity"]}},"required":["lat","lon"]},"example":{"lat":48.8584,"lon":2.2945,"language":"en"}}}},"responses":{"200":{"description":"Successful paid response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"ok":{"type":"boolean","const":true},"tool":{"type":"string","const":"coordinates-to-address"},"result":{"anyOf":[{"type":"null"},{"type":"object","additionalProperties":true,"properties":{"formatted_address":{"type":"string"},"lat":{"type":"number"},"lon":{"type":"number"},"city":{"type":"string"},"country_code":{"type":"string"}},"required":["lat","lon"]}]},"cached":{"type":"boolean"}},"required":["ok","tool","result"]}}}},"400":{"description":"Invalid request"},"402":{"description":"Payment Required","headers":{"PAYMENT-REQUIRED":{"description":"Base64-encoded x402 v2 payment challenge.","schema":{"type":"string"}}}},"413":{"description":"Request body exceeds 65,536 bytes"},"500":{"description":"Service or upstream provider failure"}}}},"/satellite-observe":{"post":{"operationId":"satellite_observe","summary":"Satellite observe","description":"Retrieve a recent or date-targeted satellite observation in true color, vegetation, water, thermal, or radar mode.","tags":["Satellite","Earth Observation"],"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.025"},"protocols":[{"x402":{}}]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"lat":{"type":"number","minimum":-90,"maximum":90},"lon":{"type":"number","minimum":-180,"maximum":180},"mode":{"type":"string","enum":["true_color","vegetation","water","thermal","radar"],"default":"true_color"},"radius_m":{"type":"integer","minimum":500,"maximum":50000,"default":3000},"date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Optional preferred acquisition date in YYYY-MM-DD format."},"date_tolerance_days":{"type":"integer","minimum":1,"maximum":60,"default":10},"max_cloud_cover":{"type":"integer","minimum":0,"maximum":100,"default":20,"description":"Optical modes only. Radar is cloud-independent."},"orbit":{"type":"string","enum":["ASCENDING","DESCENDING"],"default":"ASCENDING","description":"Sentinel-1 orbit direction for radar mode."}},"required":["lat","lon"]},"example":{"lat":25.2048,"lon":55.2708,"mode":"true_color","radius_m":3000,"date_tolerance_days":10,"max_cloud_cover":20}}}},"responses":{"200":{"description":"Successful paid response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"ok":{"type":"boolean"},"tool":{"type":"string","const":"satellite-observe"},"mode":{"type":"string"},"fulfillment_status":{"type":"string"},"selected_scene":{"type":"object","additionalProperties":true},"image":{"type":"object","additionalProperties":true,"properties":{"format":{"type":"string","const":"png"},"clean_url":{"type":"string"},"annotated_url":{"type":"string"}}},"warnings":{"type":"array","items":{"type":"string"}},"attribution":{"type":"string"}},"required":["ok","tool"]}}}},"400":{"description":"Invalid request"},"402":{"description":"Payment Required","headers":{"PAYMENT-REQUIRED":{"description":"Base64-encoded x402 v2 payment challenge.","schema":{"type":"string"}}}},"413":{"description":"Request body exceeds 65,536 bytes"},"500":{"description":"Service or upstream provider failure"}}}},"/location-risk":{"post":{"operationId":"location_risk","summary":"Location risk","description":"Return current nearby wildfire, earthquake, flood, tropical cyclone, volcano, and drought signals with deterministic risk scores. No satellite images are generated.","tags":["GeoRisk","Natural Hazards"],"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.01"},"protocols":[{"x402":{}}]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"lat":{"type":"number","minimum":-90,"maximum":90},"lon":{"type":"number","minimum":-180,"maximum":180},"hazards":{"type":"array","minItems":1,"uniqueItems":true,"items":{"type":"string","enum":["wildfire","earthquake","flood","tropical_cyclone","volcano","drought"]},"description":"Optional subset. All supported hazards are checked by default."},"radius_km":{"type":"number","minimum":1,"maximum":1000,"description":"Optional global radius override. Otherwise hazard-specific radii are used."},"days":{"type":"integer","minimum":1,"maximum":365,"description":"Optional global time-window override. Otherwise hazard-specific windows are used."},"event_limit":{"type":"integer","minimum":1,"maximum":200,"default":50},"top_events_limit":{"type":"integer","minimum":1,"maximum":50,"default":12}},"required":["lat","lon"]},"example":{"lat":13.7713,"lon":120.6627,"top_events_limit":8}}}},"responses":{"200":{"description":"Successful paid response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"ok":{"type":"boolean","const":true},"tool":{"type":"string","const":"location-risk"},"generated_at":{"type":"string"},"location":{"type":"object","properties":{"lat":{"type":"number"},"lon":{"type":"number"}},"required":["lat","lon"]},"overall_risk":{"type":"object","additionalProperties":false,"properties":{"score":{"type":"integer","minimum":0,"maximum":100},"level":{"type":"string","enum":["none","low","medium","high","severe"]},"primary_hazard":{"anyOf":[{"type":"string"},{"type":"null"}]},"secondary_hazard_boost":{"type":"integer","minimum":0}},"required":["score","level","primary_hazard","secondary_hazard_boost"]},"active_hazard_count":{"type":"integer","minimum":0},"hazards":{"type":"object","additionalProperties":{"type":"object","additionalProperties":true}},"top_nearby_events":{"type":"array","items":{"type":"object","additionalProperties":true}},"satellite_images_included":{"type":"boolean","const":false}},"required":["ok","tool","location","overall_risk","hazards","satellite_images_included"]}}}},"400":{"description":"Invalid request"},"402":{"description":"Payment Required","headers":{"PAYMENT-REQUIRED":{"description":"Base64-encoded x402 v2 payment challenge.","schema":{"type":"string"}}}},"413":{"description":"Request body exceeds 65,536 bytes"},"500":{"description":"Service or upstream provider failure"}}}}}}