Unofficial OpenAPI specification for Nominatim API provided by OpenStreetMap project.
Open sparkfabrik.github.io/nominatim-openapi in a browser. Choose the endpoint you are interested in and click on "Try it out". Fill all needed options and click on "Execute", you can see query and results under the "Responses" section.
You can download the formal API specification from here: sparkfabrik.github.io/nominatim-openapi/nominatim.openapi.json.
Nominatim by OpenStreetMap is one of the best FOSS alternative for geolocation tasks, both as a service and self-hosted.
Exposed API is well documented by the official documentation, but it lacks a formal specification such as the well-known OpenAPI (a de-facto standard for REST API).
Some drawbacks of actual API implementation (waiting for version 2, see the planning board) can not be represented by OpenAPI and JSON Schema specifications, but we think that also a partial description can be very useful for end-users and developers (think about code generators for client and server).
This project aims to fill the hole and offer to community a robust, modern, and machine-readable description of the Nominatim API.
Getting started section shows how to use the official interactive playground hosted by Github Pages.
If you want to locally run your own playground, you must download this repository (via zip download or git clone).
All relevant files are in docs/ folder.
You can't simply open the docs/index.html file in your browser, because of default Cross-Origin Policy. So you need to serve docs/ folder using a web server running locally.
In a javascript-ready environment (ie. with node and npm installed),
you can run npx -y http-server ./docs in a terminal from the project folder and point your browser to http://localhost:8080.
In a Docker-ready environment, you can run make ui to have the playground exposed on http://localhost:8091.
You can verify the integrity of deployed spec using the sha512 checksum provided.
You can run make checksum and make verify to compute and verify the checksum.
Refs: #6.
A this early stage, we are discussing the roadmap in a dedicated issue. When ready, the following table will be updated.
| Milestone | Task | TBD | To do | Doing | Done | Refs |
|---|---|---|---|---|---|---|
| OpenAPI Spec | /search endpoint |
■ | #2 | |||
/reverse endpoint |
■ | #3 | ||||
/lookup endpoint |
■ | #4 | ||||
/status endpoint |
■ | #5 | ||||
/details endpoint |
■ | |||||
| Node CLI | ■ |
Any contribution is welcome! Please read and accept our Code of Conduct, then refer to Contributing Guidelines before opening issues or pull requests.
First of all, search for issues or open one to share your thoughts, needs or intents with the maintainers and the community.
Then 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.
Please 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.
- pre-commit - compute sha512 checksum of
nominatim.openapi.jsonand write onnominatim.openapi.json.checksumfile. - pre-push - verify the
nominatim.openapi.jsonchecksum againstnominatim.openapi.json.checksumfile.
In a Docker-ready environment, you can run make editor to have the new Swagger Editor up and running on http://localhost:8092.
Automatic file loading and saving is not available, so you must copy/paste the content of nominatim.openapi.json in the editor and then copy/paste it back to save the changes.
Website: https://www.openapis.org
Repository: https://github.com/oai
Also known as: Swagger (see history)
Latest version: v3.1.0
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.
Website: https://swagger.io/tools/swagger-ui/
Repository: https://github.com/swagger-api/swagger-ui
Latest version: v5.1.0
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.
Website: https://www.openstreetmap.org
Repository: https://github.com/openstreetmap
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.
Website: https://nominatim.org
Repository: https://github.com/osm-search
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.
Website: https://developer.mozilla.org/en-US/docs/Web/Security/Subresource_Integrity
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.
Website: https://en.wikipedia.org/wiki/SHA-2
The Secure Hash Algorithms are a family of cryptographic hash functions published by the National Institute of Standards and Technology (NIST).
Nominatim (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.
- The
formatparameter (docs) accepts 5 values (xml,json,jsonv2,geojson,geocodejson), but onlyjsonv2(the default one) is described by this specification incomponents.schemas(see Nominatim/issues/1697 and OpenAPI-Specification/issues/2031 for further informations). - In
jsonv2responses some numeric values are represented by strings for historical reasons (see this discussion), so this specification.
This project would not exist without open source, it is open source, and the community behind it contributes to open source.
Here is a list of external contributions (code and discussions) starting from work for this project:
- fix typos in Nominatim error messages: Nominatim/pull/3112
- discussion about
jsonv2format of Nominatim responses: Nominatim/discussions/3115 - ...
MIT license on OpenAPI Specification. Geolocated data from OSM are provided under the ODbL license. Please read and accept the Nominatim Usage Policy before any use.
Many thanks to all OpenStreetMap contributors.
Pictures for this project are generated using Midjourney.
