{"openapi":"3.1.0","info":{"title":"@mailwoman/nominatim","version":"7.8.1","description":"Nominatim drop-in — a Nominatim-compatible HTTP geocoding API (search / reverse / lookup / status) over the Mailwoman engine. Run it with `npx @mailwoman/nominatim serve`.","license":{"name":"AGPL-3.0-only OR LicenseRef-Commercial","identifier":"AGPL-3.0-only"},"contact":{"name":"Sister Software","url":"https://mailwoman.sister.software"}},"externalDocs":{"description":"Switching from Nominatim","url":"https://mailwoman.sister.software/docs/concepts/switching-from-nominatim"},"servers":[{"url":"http://{host}:{port}","variables":{"host":{"default":"127.0.0.1"},"port":{"default":"8080"}}}],"tags":[{"name":"geocoding","description":"Forward geocoding, reverse geocoding, and OSM id lookup."},{"name":"meta","description":"Health and deploy-time operations."}],"security":[],"components":{"schemas":{"NominatimSearchResponse":{"anyOf":[{"type":"array","items":{"$ref":"#/components/schemas/NominatimResult"}},{"$ref":"#/components/schemas/NominatimFeatureCollection"},{"type":"array","items":{"$ref":"#/components/schemas/SchemaOrgPlace"}}]},"NominatimResult":{"type":"object","properties":{"place_id":{"anyOf":[{"type":"number"},{"type":"string"}]},"licence":{"type":"string"},"osm_type":{"type":"string"},"osm_id":{"anyOf":[{"type":"number"},{"type":"string"}]},"lat":{"type":"string"},"lon":{"type":"string"},"display_name":{"type":"string"},"boundingbox":{"type":"array","prefixItems":[{"type":"string"},{"type":"string"},{"type":"string"},{"type":"string"}]},"class":{"type":"string"},"type":{"type":"string"},"importance":{"type":"number"},"place_rank":{"type":"number"},"address":{"$ref":"#/components/schemas/NominatimAddressDetails"},"geojson":{},"annotations":{"type":"object","properties":{},"additionalProperties":{}}},"required":["place_id","licence","lat","lon","display_name"],"additionalProperties":{}},"NominatimAddressDetails":{"type":"object","properties":{"house_number":{"type":"string"},"road":{"type":"string"},"neighbourhood":{"type":"string"},"suburb":{"type":"string"},"city":{"type":"string"},"town":{"type":"string"},"village":{"type":"string"},"county":{"type":"string"},"state":{"type":"string"},"postcode":{"type":"string"},"country":{"type":"string"},"country_code":{"type":"string"}},"additionalProperties":{}},"NominatimFeatureCollection":{"type":"object","properties":{"type":{"type":"string","enum":["FeatureCollection"]},"features":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["Feature"]},"properties":{"type":"object","properties":{},"additionalProperties":{}},"geometry":{},"bbox":{"type":"array","prefixItems":[{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"}]}},"required":["type","properties"]}}},"required":["type","features"]},"SchemaOrgPlace":{"type":"object","properties":{"@context":{"type":"string","enum":["https://schema.org"]},"@type":{"type":"string","enum":["Place"]},"name":{"type":"string"},"geo":{"$ref":"#/components/schemas/SchemaOrgGeoCoordinates"},"address":{"$ref":"#/components/schemas/SchemaOrgPostalAddress"}},"required":["@context","@type"]},"SchemaOrgGeoCoordinates":{"type":"object","properties":{"@type":{"type":"string","enum":["GeoCoordinates"]},"latitude":{"type":"number"},"longitude":{"type":"number"}},"required":["@type","latitude","longitude"]},"SchemaOrgPostalAddress":{"type":"object","properties":{"@type":{"type":"string","enum":["PostalAddress"]},"streetAddress":{"type":"string"},"postOfficeBoxNumber":{"type":"string"},"addressLocality":{"type":"string"},"addressRegion":{"type":"string"},"postalCode":{"type":"string"},"addressCountry":{"type":"string"}},"required":["@type"]},"Error":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]},"NominatimReverseResponse":{"anyOf":[{"$ref":"#/components/schemas/NominatimResult"},{"type":"null"},{"$ref":"#/components/schemas/NominatimFeatureCollection"},{"$ref":"#/components/schemas/SchemaOrgPlace"}]},"NominatimLookupResponse":{"anyOf":[{"type":"array","items":{"$ref":"#/components/schemas/NominatimResult"}},{"$ref":"#/components/schemas/NominatimFeatureCollection"}]},"NominatimStatus":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"data_updated":{"type":"string"}},"required":["status","message"]}},"parameters":{}},"paths":{"/":{"get":{"operationId":"getRoot","summary":"Landing page","tags":["meta"],"responses":{"200":{"description":"HTML landing page.","content":{"text/html":{"schema":{"type":"string"}}}}}}},"/search":{"get":{"operationId":"search","summary":"Forward geocoding (free-text or structured)","tags":["geocoding"],"parameters":[{"schema":{"type":"string","description":"Free-text query. Mutually exclusive with the structured fields."},"required":false,"description":"Free-text query. Mutually exclusive with the structured fields.","name":"q","in":"query"},{"schema":{"type":"string","description":"Structured: house number and street name."},"required":false,"description":"Structured: house number and street name.","name":"street","in":"query"},{"schema":{"type":"string","description":"Structured: city."},"required":false,"description":"Structured: city.","name":"city","in":"query"},{"schema":{"type":"string","description":"Structured: county."},"required":false,"description":"Structured: county.","name":"county","in":"query"},{"schema":{"type":"string","description":"Structured: state."},"required":false,"description":"Structured: state.","name":"state","in":"query"},{"schema":{"type":"string","description":"Structured: country."},"required":false,"description":"Structured: country.","name":"country","in":"query"},{"schema":{"type":"string","description":"Structured: postal code."},"required":false,"description":"Structured: postal code.","name":"postalcode","in":"query"},{"schema":{"type":"string","description":"Comma-separated ISO 3166-1 alpha-2 codes restricting results."},"required":false,"description":"Comma-separated ISO 3166-1 alpha-2 codes restricting results.","name":"countrycodes","in":"query"},{"schema":{"type":"string","enum":["0","1"],"description":"Restrict to the viewbox."},"required":false,"description":"Restrict to the viewbox.","name":"bounded","in":"query"},{"schema":{"type":"integer","description":"Maximum results (default 10)."},"required":false,"description":"Maximum results (default 10).","name":"limit","in":"query"},{"schema":{"type":"string","enum":["0","1"],"description":"Include the address breakdown."},"required":false,"description":"Include the address breakdown.","name":"addressdetails","in":"query"},{"schema":{"type":"string","enum":["jsonv2","json","geojson","jsonld"],"description":"Output format (default jsonv2)."},"required":false,"description":"Output format (default jsonv2).","name":"format","in":"query"},{"schema":{"type":"string","description":"Preferred result language."},"required":false,"description":"Preferred result language.","name":"accept-language","in":"query"}],"responses":{"200":{"description":"A jsonv2 result array (or a geojson FeatureCollection / jsonld Place[] per `format`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NominatimSearchResponse"}}}},"500":{"description":"An unexpected engine fault. A clean JSON error, never a stack trace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"501":{"description":"The backing engine method is not wired for this deployment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/reverse":{"get":{"operationId":"reverse","summary":"Reverse geocoding","tags":["geocoding"],"parameters":[{"schema":{"type":"number","description":"Latitude."},"required":false,"description":"Latitude.","name":"lat","in":"query"},{"schema":{"type":"number","description":"Longitude."},"required":false,"description":"Longitude.","name":"lon","in":"query"},{"schema":{"type":"integer","description":"Detail level."},"required":false,"description":"Detail level.","name":"zoom","in":"query"},{"schema":{"type":"string","enum":["0","1"],"description":"Include the address breakdown."},"required":false,"description":"Include the address breakdown.","name":"addressdetails","in":"query"},{"schema":{"type":"string","enum":["jsonv2","json","geojson","jsonld"],"description":"Output format (default jsonv2)."},"required":false,"description":"Output format (default jsonv2).","name":"format","in":"query"},{"schema":{"type":"string","description":"Preferred result language."},"required":false,"description":"Preferred result language.","name":"accept-language","in":"query"}],"responses":{"200":{"description":"A single jsonv2 result (or `null`; a geojson FeatureCollection / jsonld Place per `format`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NominatimReverseResponse"}}}},"400":{"description":"Missing or out-of-range `lat`/`lon`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"An unexpected engine fault. A clean JSON error, never a stack trace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"501":{"description":"The backing engine method is not wired for this deployment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/lookup":{"get":{"operationId":"lookup","summary":"Look up places by OSM id","tags":["geocoding"],"parameters":[{"schema":{"type":"string","description":"Comma-separated OSM ids (N|W|R-prefixed)."},"required":false,"description":"Comma-separated OSM ids (N|W|R-prefixed).","name":"osm_ids","in":"query"},{"schema":{"type":"string","enum":["0","1"],"description":"Include the address breakdown."},"required":false,"description":"Include the address breakdown.","name":"addressdetails","in":"query"},{"schema":{"type":"string","enum":["jsonv2","json","geojson","jsonld"],"description":"Output format (default jsonv2)."},"required":false,"description":"Output format (default jsonv2).","name":"format","in":"query"}],"responses":{"200":{"description":"A jsonv2 result array (or a geojson FeatureCollection when format=geojson).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NominatimLookupResponse"}}}},"500":{"description":"An unexpected engine fault. A clean JSON error, never a stack trace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"501":{"description":"The backing engine method is not wired for this deployment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/status":{"get":{"operationId":"status","summary":"Engine health","tags":["meta"],"responses":{"200":{"description":"Engine health. Absent `engine.status` answers `{status: 0, message: \"OK\"}` — never 501.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NominatimStatus"}}}},"500":{"description":"An unexpected engine fault. A clean JSON error, never a stack trace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"webhooks":{}}