{"id":18947293,"url":"https://github.com/sparkfabrik/nominatim-openapi","last_synced_at":"2025-04-15T22:31:38.980Z","repository":{"id":179384461,"uuid":"663113476","full_name":"sparkfabrik/nominatim-openapi","owner":"sparkfabrik","description":"OpenAPI specification for OpenStreetMap Nominatim API (unofficial).","archived":false,"fork":false,"pushed_at":"2023-11-22T13:52:09.000Z","size":5971,"stargazers_count":7,"open_issues_count":2,"forks_count":1,"subscribers_count":6,"default_branch":"main","last_synced_at":"2025-03-29T04:04:27.930Z","etag":null,"topics":["json-schema","nominatim","openapi","openstreetmap","swagger"],"latest_commit_sha":null,"homepage":"https://sparkfabrik.github.io/nominatim-openapi/","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sparkfabrik.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":"SECURITY.md","support":null,"governance":null}},"created_at":"2023-07-06T15:21:57.000Z","updated_at":"2025-03-04T19:03:21.000Z","dependencies_parsed_at":"2023-11-22T14:35:52.347Z","dependency_job_id":null,"html_url":"https://github.com/sparkfabrik/nominatim-openapi","commit_stats":null,"previous_names":["sparkfabrik/nominatim-openapi"],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sparkfabrik%2Fnominatim-openapi","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sparkfabrik%2Fnominatim-openapi/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sparkfabrik%2Fnominatim-openapi/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sparkfabrik%2Fnominatim-openapi/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sparkfabrik","download_url":"https://codeload.github.com/sparkfabrik/nominatim-openapi/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249166143,"owners_count":21223392,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["json-schema","nominatim","openapi","openstreetmap","swagger"],"created_at":"2024-11-08T13:09:31.679Z","updated_at":"2025-04-15T22:31:33.968Z","avatar_url":"https://github.com/sparkfabrik.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Nominatim OpenAPI Specification\n\nUnofficial OpenAPI Specification (OAS) for Nominatim API provided by OpenStreetMap project (OSM).\n\n\u003cp align=\"center\"\u003e\u003cimg src=\"./docs/logo-square.png\" width=\"50%\" /\u003e\u003c/p\u003e\n\n## Getting started\n\nOpen [sparkfabrik.github.io/nominatim-openapi](https://sparkfabrik.github.io/nominatim-openapi/) in a browser.\nChoose the endpoint you are interested in and click on \"Try it out\".\nFill all needed options and click on \"Execute\", you can see query and results under the \"Responses\" section.\n\nYou can download the formal API specification from here: [sparkfabrik.github.io/nominatim-openapi/nominatim.openapi.json](https://sparkfabrik.github.io/nominatim-openapi/nominatim.openapi.json).\n\n## Context and motivations\n\nNominatim by OpenStreetMap is one of the best FOSS alternative for geolocation tasks, both as a service and self-hosted.\n\nExposed API is well documented by the [official documentation](https://nominatim.org/release-docs/develop/),\nbut it lacks a [formal specification such as the well-known OpenAPI](https://github.com/osm-search/Nominatim/issues/1697) (a de-facto standard for REST API).\n\nSome drawbacks of actual API implementation (waiting for version 2, see the [planning board](https://github.com/osm-search/Nominatim/projects/1)) can not be represented by OpenAPI and JSON Schema specifications,\nbut we think that also a partial description can be very useful for end-users and developers (think about [code generators for client and server](https://openapi-generator.tech/docs/generators/)).\n\nThis project aims to fill the hole and offer to community a robust, modern, and machine-readable description of the Nominatim API.\n\n## How to use\n\n### Playground\n\nGetting started section shows how to use the [official interactive playground]((https://sparkfabrik.github.io/nominatim-openapi/)) hosted by [Github Pages](https://pages.github.com/).\nIf you want to locally run your own playground, you must download this repository (via [zip download](https://github.com/sparkfabrik/nominatim-openapi/archive/refs/heads/main.zip) or `git clone`).\n\n\u003e Source of OAS is in `src/` folder, all final files (bundled and minified) are in `docs/` folder.\n\nYou can't simply open the `docs/index.html` file in your browser, because of default [Cross-Origin Policy](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS/Errors).\nSo you need to serve `docs/` folder using a web server running locally.\n\nIn a javascript-ready environment (ie. with [node](https://nodejs.org/en) and [npm](https://www.npmjs.com/) installed),\nyou can run `make serve` in a terminal from the project folder and point your browser to `http://localhost:8080`.\n\nIn a Docker-ready environment, you can run `make ui` to have the playground exposed on `http://localhost:8091`.\n\n### Security\n\nYou can verify the integrity of [deployed spec](https://sparkfabrik.github.io/nominatim-openapi/nominatim.openapi.json)\nusing the [sha512 checksum provided](https://github.com/sparkfabrik/nominatim-openapi/blob/main/docs/nominatim.openapi.json.checksum).\n\nYou can run `make checksum` and `make verify` to compute and verify the checksum.\n\nRefs: #6.\n\n### Versioning\n\nThis spec follows the Nominatim API versioning, so it use the [same tags](https://github.com/osm-search/Nominatim/tags) of the original project.\n\n## Roadmap\n\nA this early stage, we are discussing the roadmap in a [dedicated issue](https://github.com/sparkfabrik/nominatim-openapi/issues/1).\nWhen ready, the following table will be updated.\n\n| Milestone | Task | TBD | To do | Doing | Done | Refs |\n| --------- | ---- | --- | ----- | ----- | ---- | ---- |\n| OpenAPI Spec | `/search` endpoint | | | | ■ | [#2](https://github.com/sparkfabrik/nominatim-openapi/issues/2) |\n| | `/lookup` endpoint | | | | ■ | [#4](https://github.com/sparkfabrik/nominatim-openapi/issues/4) |\n| | `/reverse` endpoint | | | | ■ | [#3](https://github.com/sparkfabrik/nominatim-openapi/issues/3) |\n| | `/status` endpoint | | | | ■ | [#5](https://github.com/sparkfabrik/nominatim-openapi/issues/5) |\n| | `/details` endpoint | | | | ■ | [#13](https://github.com/sparkfabrik/nominatim-openapi/issues/13) |\n| | `/deletable` endpoint | | | | ■ | [#13](https://github.com/sparkfabrik/nominatim-openapi/issues/13) |\n| | `/polygons` endpoint | | | | ■ | [#13](https://github.com/sparkfabrik/nominatim-openapi/issues/13) |\n| Test suite | | ■ | | | | |\n| Node CLI | | ■ | | | | |\n\n## Contributing\n\nAny contribution is welcome!\n\nPlease read and accept our [Code of Conduct](https://github.com/sparkfabrik/nominatim-openapi/blob/main/CODE_OF_CONDUCT.md),\nthen refer to [Contributing Guidelines](https://github.com/sparkfabrik/nominatim-openapi/blob/main/CONTRIBUTING.md) before opening issues or pull requests.\n\n### Contributions to OpenAPI Specification\n\nFirst of all, search for issues or open one to share your thoughts, needs or intents with the maintainers and the community.\nThen fork and clone this repo, make your changes, commit and push them on a new branch, finally open a PR against `main` branch of this repo.\n\nPre-requisites: [git](https://git-scm.com/), [make](https://www.gnu.org/software/make/), [shasum](https://www.commandlinux.com/man-page/man1/shasum.1.html), [npx](https://www.npmjs.com/package/npx) (node and npm), [docker](https://www.docker.com/).\n\nEditable source of OAS is in `src/` folder. You can validate it running `make validate`. You can bundle it running `make build`.\n\nPlease activate the Git Hooks provided in `.githooks/` folder before the first change (hooks are bash scripts). You can simply run `make hooks` to activate them.\n- **pre-commit** - validate and bundle OAS spec, compute sha512 checksums.\n- **pre-push** - verify the checksums.\n\nIn a Docker-ready environment, you can run `make editor` to have the new Swagger Editor up and running on `http://localhost:8092`.\nAutomatic file loading and saving is not available, so you must copy/paste the content of `src/nominatim.openapi.json` in the editor and then copy/paste it back to save the changes.\n\n\u003cp align=\"center\"\u003e\u003cimg src=\"./docs/logo-wide.png\" width=\"50%\" /\u003e\u003c/p\u003e\n\n## FAQ\n\n### What is OpenAPI?\n\nWebsite: https://www.openapis.org\n\nRepository: https://github.com/oai\n\nAlso known as: Swagger (see [history](https://youtu.be/_G9dlv66-xw))\n\nLatest version: v3.1.0\n\n\u003e The OpenAPI Specification (OAS) is a specification language for HTTP APIs that provides a standardized means to define your API to others. You can quickly discover how an API works, configure infrastructure, generate client code, and create test cases for your APIs. Read more about how you can get control of your APIs now, understand the full API lifecycle and communicate with developer communities inside and outside your organization.\n\n### What is JSON Schema?\n\nWebsite: https://json-schema.org\n\nRepository: https://github.com/json-schema-org\n\nLatest version: v2020-12\n\n\u003e JSON Schema enables the confident and reliable use of the JSON data format.\n\n### What is Swagger UI?\n\nWebsite: https://swagger.io/tools/swagger-ui/\n\nRepository: https://github.com/swagger-api/swagger-ui\n\nLatest version: v5.1.0\n\n\u003e Swagger UI allows anyone - be it your development team or your end consumers - to visualize and interact with the API's resources without having any of the implementation logic in place. It's automatically generated from your OpenAPI (formerly known as Swagger) Specification, with the visual documentation making it easy for back end implementation and client side consumption.\n\n### What is OpenStreetMap?\n\nWebsite: https://www.openstreetmap.org\n\nRepository: https://github.com/openstreetmap\n\n\u003e OpenStreetMap is a map of the world, created by people like you and free to use under an open license. It is built by a community of mappers that contribute and maintain data about roads, trails, cafés, railway stations, and much more, all over the world.\n\n### What is Nominatim?\n\nWebsite: https://nominatim.org\n\nRepository: https://github.com/osm-search\n\n\u003e Nominatim uses OpenStreetMap data to find locations on Earth by name and address (geocoding). It can also do the reverse, find an address for any location on the planet.\n\n### What is GeoJSON?\n\nWebsite: https://geojson.org\n\nRepository: https://github.com/geojson\n\n\u003e GeoJSON is a format for encoding a variety of geographic data structures.\n\n### What is GeocodeJSON?\n\nWebsite: https://github.com/geocoders/geocodejson-spec/tree/master/draft\n\nRepository: https://github.com/geocoders/geocodejson-spec\n\n\u003e This specification attempts to create a standard for handling geocoding results.\n\n### What is Subresource Integrity (SRI)\n\nWebsite: https://developer.mozilla.org/en-US/docs/Web/Security/Subresource_Integrity\n\n\u003e Subresource Integrity (SRI) is a security feature that enables browsers to verify that resources they fetch e delivered without unexpected manipulation. It works by allowing you to provide a cryptographic hash that a fetched resource must match.\n\n### What are Secure Hash Algorithms (SHA)\n\nWebsite: https://en.wikipedia.org/wiki/SHA-2\n\n\u003e The Secure Hash Algorithms are a family of cryptographic hash functions published by the National Institute of Standards and Technology (NIST).\n\n## Drawbacks\n\nNominatim (and OpenStreetMap) project have a long story and a non trivial development path, so this OpenAPI specification reflects some features of actual software and official documentation.\n\n- The `format` parameter ([docs](https://nominatim.org/release-docs/develop/api/Search/#output-format)) accepts 5 values (`xml`, `json`, `jsonv2`, `geojson`, `geocodejson`), where `jsonv2` is the default one, but this specification describes only the `geocodejson` format in `components.schemas` (see [Nominatim/discussions/3115](https://github.com/osm-search/Nominatim/discussions/3115#discussioncomment-6486249), [Nominatim/issues/1697](https://github.com/osm-search/Nominatim/issues/1697#issuecomment-726232719), and [OpenAPI-Specification/issues/2031](https://github.com/OAI/OpenAPI-Specification/issues/2031) for further informations).\n\n## Open Source Software\n\nThis project would not exist without open source, it is open source, and the community behind it contributes to open source.\n\nHere is a list of external contributions (code and discussions) starting from work for this project:\n- release of the official schema for `geocodejson` spec: [geocodejson-spec/pull/25](https://github.com/geocoders/geocodejson-spec/pull/25) (see also [geocodejson-spec/issues/21](https://github.com/geocoders/geocodejson-spec/issues/21))\n- fix typos in Nominatim error messages: [Nominatim/pull/3112](https://github.com/osm-search/Nominatim/pull/3112)\n- release of an unofficial schema for [GeoHash](http://geohash.org/) format (see [jenkin/json-schema-bricks](https://github.com/jenkin/json-schema-bricks))\n- release of an unofficial schema for [SemVer](https://semver.org/) format (see [jenkin/json-schema-bricks](https://github.com/jenkin/json-schema-bricks))\n- discussion about `jsonv2` and `geocodejson` formats of Nominatim responses: [Nominatim/discussions/3115](https://github.com/osm-search/Nominatim/discussions/3115)\n- ...\n\n## License\n\nMIT license on OpenAPI Specification.\nGeolocated data from OSM are provided under the [ODbL](https://openstreetmap.org/copyright) license.\nPlease read and accept the [Nominatim Usage Policy](https://operations.osmfoundation.org/policies/nominatim/) before any use.\n\n## Acknowledgements\n\nMany thanks to all OpenStreetMap contributors.\n\nPictures for this project are generated using [Midjourney](https://www.midjourney.com/).\n\n\u003cp align=\"center\"\u003e\u003cimg src=\"./docs/logo-close.png\" width=\"50%\" /\u003e\u003c/p\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsparkfabrik%2Fnominatim-openapi","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsparkfabrik%2Fnominatim-openapi","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsparkfabrik%2Fnominatim-openapi/lists"}