{"openapi":"3.1.0","info":{"title":"LocaleSense","version":"1.0.0","description":"Commerce intelligence from an IP address: currency, formatting, locale, tax, local payment methods, live central-bank FX and fraud signals."},"servers":[{"url":"https:\/\/localesense.com"}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Your API key, as `Authorization: Bearer ls_live_...`"}}},"security":[{"bearerAuth":[]}],"paths":{"\/v1\/self":{"get":{"summary":"The caller's own commerce profile","description":"Detects the caller from the edge headers and returns their full commerce profile. This is the call you put in front of a checkout. Requires the Free tier or above.","operationId":"lookup_self","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success"},"401":{"description":"Unauthenticated"},"403":{"description":"Tier or origin restriction"},"422":{"description":"Validation or geo-lookup failure"},"429":{"description":"Rate limit or quota exceeded"}}}},"\/v1\/lookup":{"get":{"summary":"The commerce profile for any IP","description":"Same payload as \/v1\/self, for an address you supply. Use it to enrich logs, orders or a CRM after the fact. Requires the Free tier or above.","operationId":"lookup_ip","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success"},"401":{"description":"Unauthenticated"},"403":{"description":"Tier or origin restriction"},"422":{"description":"Validation or geo-lookup failure"},"429":{"description":"Rate limit or quota exceeded"}},"parameters":[{"name":"ip","in":"query","required":true,"description":"Required. A public IPv4 or IPv6 address.","schema":{"type":"string"}}]}},"\/v1\/batch":{"post":{"summary":"Up to 100 addresses in one call","description":"Results come back in request order. One unresolvable address does not fail the batch \u2014 it returns an error object in its own slot. Requires the Pro tier or above.","operationId":"batch","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success"},"401":{"description":"Unauthenticated"},"403":{"description":"Tier or origin restriction"},"422":{"description":"Validation or geo-lookup failure"},"429":{"description":"Rate limit or quota exceeded"}},"requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","properties":{"ips":{"type":"array","items":{"type":"string"},"maxItems":100,"description":"Required. An array of 1-100 IP addresses."}},"required":["ips"]}}}}}},"\/v1\/fraud\/check":{"post":{"summary":"A card's issuing country against the IP presenting it","description":"The signal no geo API offers: an IP in Pakistan paired with a card issued in Nigeria. Returns bin_country_match (three-valued \u2014 null when either side is genuinely unknown), the network posture, and a composite risk score. Send only the first 6-8 digits of the card; a full card number is rejected at validation. Requires the Business tier or above.","operationId":"fraud_check","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success"},"401":{"description":"Unauthenticated"},"403":{"description":"Tier or origin restriction"},"422":{"description":"Validation or geo-lookup failure"},"429":{"description":"Rate limit or quota exceeded"}},"requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","properties":{"ip":{"type":"string","description":"Required. The address presenting the card."},"bin":{"type":"string","description":"Required. The first 6-8 digits of the card number. Never the full PAN."}},"required":["ip","bin"]}}}}}},"\/v1\/countries":{"get":{"summary":"Every country profile","description":"The whole moat table in one payload \u2014 not paginated, because building a country selector should not require walking pages. Requires the Free tier or above.","operationId":"api_countries_index","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success"},"401":{"description":"Unauthenticated"},"403":{"description":"Tier or origin restriction"},"422":{"description":"Validation or geo-lookup failure"},"429":{"description":"Rate limit or quota exceeded"}}}},"\/v1\/countries\/{cc}":{"get":{"summary":"One country profile","description":"A single country by ISO 3166-1 alpha-2 code. No IP involved. Requires the Free tier or above.","operationId":"api_countries_show","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success"},"401":{"description":"Unauthenticated"},"403":{"description":"Tier or origin restriction"},"422":{"description":"Validation or geo-lookup failure"},"429":{"description":"Rate limit or quota exceeded"}},"parameters":[{"name":"cc","in":"path","required":true,"description":"Required. ISO 3166-1 alpha-2, e.g. PK.","schema":{"type":"string"}}]}},"\/v1\/fx":{"get":{"summary":"Latest central-bank rates","description":"Every published rate against a base currency. Sourced from central banks \u2014 never a reseller. Requires the Free tier or above.","operationId":"fx_latest","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success"},"401":{"description":"Unauthenticated"},"403":{"description":"Tier or origin restriction"},"422":{"description":"Validation or geo-lookup failure"},"429":{"description":"Rate limit or quota exceeded"}},"parameters":[{"name":"base","in":"query","required":false,"description":"Optional. ISO 4217, defaults to USD.","schema":{"type":"string"}}]}},"\/v1\/fx\/convert":{"get":{"summary":"Convert an amount between currencies","description":"Arbitrary-precision conversion (bcmath, scale 12). Amounts are strings, never floats \u2014 a float cannot hold money. Requires the Free tier or above.","operationId":"fx_convert","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success"},"401":{"description":"Unauthenticated"},"403":{"description":"Tier or origin restriction"},"422":{"description":"Validation or geo-lookup failure"},"429":{"description":"Rate limit or quota exceeded"}},"parameters":[{"name":"from","in":"query","required":true,"description":"Required. ISO 4217.","schema":{"type":"string"}},{"name":"to","in":"query","required":true,"description":"Required. ISO 4217.","schema":{"type":"string"}},{"name":"amount","in":"query","required":true,"description":"Required. A decimal string.","schema":{"type":"string"}}]}},"\/v1\/fx\/historical\/{date}":{"get":{"summary":"Rates as they stood on a date","description":"The rates a central bank published on a given day. Useful for reconciling a historical order at the rate that actually applied. Requires the Business tier or above.","operationId":"fx_historical","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success"},"401":{"description":"Unauthenticated"},"403":{"description":"Tier or origin restriction"},"422":{"description":"Validation or geo-lookup failure"},"429":{"description":"Rate limit or quota exceeded"}},"parameters":[{"name":"date","in":"path","required":true,"description":"Required. YYYY-MM-DD.","schema":{"type":"string"}},{"name":"base","in":"query","required":false,"description":"Optional. ISO 4217, defaults to USD.","schema":{"type":"string"}}]}},"\/v1\/health":{"get":{"summary":"FX source staleness","description":"Which sources are healthy and which are stale. The only endpoint that needs no API key \u2014 status pages should not require credentials. No API key required.","operationId":"health","security":[],"responses":{"200":{"description":"Success"},"401":{"description":"Unauthenticated"},"403":{"description":"Tier or origin restriction"},"422":{"description":"Validation or geo-lookup failure"},"429":{"description":"Rate limit or quota exceeded"}}}}}}