# Coordinate Parser
[](https://github.com/17swifts/coordinate-parser/actions/workflows/ci.yml)
[](https://badge.fury.io/py/coordinate-parser)
[](https://www.python.org/downloads/)
A robust Python library for parsing geographic coordinates in various formats. This library can handle decimal degrees, degrees/minutes/seconds, and maritime coordinate formats with high precision.
## Features
- **Multiple format support**: Decimal degrees, degrees/minutes/seconds, maritime formats
- **Flexible input**: Accepts strings, floats, integers, and Decimal types
- **Validation**: Optional coordinate validation with customizable ranges
- **High precision**: Uses Python's Decimal type for accurate calculations
- **Maritime formats**: Special support for nautical coordinate formats
- **Internationalization**: Supports Cyrillic cardinal directions
- **Error handling**: Comprehensive error messages for invalid inputs
## Installation
```bash
pip install coordinate-parser
```
## Quick Start
```python
from coordinate_parser import parse_coordinate
# Basic usage
lat = parse_coordinate("40°41.65'N")
lon = parse_coordinate("74°02.54'W")
print(f"Latitude: {lat}, Longitude: {lon}")
# Decimal degrees
coord = parse_coordinate("23.43")
print(f"Coordinate: {coord}")
# With validation
lat = parse_coordinate("45.5", coord_type="latitude")
lon = parse_coordinate("120.5", coord_type="longitude")
```
## Supported Formats
### Decimal Degrees
```python
parse_coordinate("23.43") # 23.43
parse_coordinate("-45.21") # -45.21
parse_coordinate("23.43 N") # 23.43
parse_coordinate("45.21 W") # -45.21
```
### Degrees and Minutes
```python
parse_coordinate("23° 25.800'") # 23.43
parse_coordinate("23 25.8 N") # 23.43
parse_coordinate("45°12.6'S") # -45.21
```
### Degrees, Minutes, and Seconds
```python
parse_coordinate("23° 25' 48.0\" N") # 23.43
parse_coordinate("45° 12' 36.0\" S") # -45.21
parse_coordinate("23d 25m 48s") # 23.43
```
### Maritime Formats
```python
# Pattern 1: degree-dash-minutes with degree symbol
parse_coordinate("40°–41.65'N") # 40.694166666667
parse_coordinate("139°-02.54'E") # 139.042333333333
# Pattern 2: degree-dash-minutes without degree symbol
parse_coordinate("54-05.48N") # 54.091333333333
parse_coordinate("162-29.03W") # -162.483833333333
# Pattern 3: degree-minutes with degree symbol
parse_coordinate("30°34.4'N") # 30.573333333333
parse_coordinate("120°45.5'E") # 120.758333333333
# Pattern 4: degree-minutes-seconds
parse_coordinate("30°34'24.0\"N") # 30.573333333333
```
### International Support
```python
# Cyrillic cardinal directions
parse_coordinate("23.43 С") # North (С = N)
parse_coordinate("45.21 З") # West (З = W)
parse_coordinate("23.43 В") # East (В = E)
parse_coordinate("45.21 Ю") # South (Ю = S)
# Comma as decimal separator
parse_coordinate("23,43") # 23.43
parse_coordinate("23° 25,8'") # 23.43
```
## API Reference
### `parse_coordinate(string, coord_type="coordinate", validate=True)`
Parse a coordinate string and return a Decimal value in decimal degrees.
**Parameters:**
- `string` (str | float | Decimal | None): The coordinate to parse
- `coord_type` (str): Type of coordinate for validation ("latitude", "longitude", or "coordinate")
- `validate` (bool): Whether to validate the coordinate is within valid ranges
**Returns:**
- `Decimal | None`: The parsed coordinate in decimal degrees, or None if input is None/empty
**Raises:**
- `ValueError`: If the coordinate cannot be parsed or is outside valid range
### `to_dec_deg(*args)`
Convert degrees, minutes, seconds to decimal degrees.
**Parameters:**
- `*args`: Variable arguments representing degrees, minutes (optional), seconds (optional)
**Returns:**
- `float`: Decimal degrees
## Validation
The library supports optional validation for coordinates:
```python
# Latitude validation (-90 to 90)
parse_coordinate("45.5", coord_type="latitude") # Valid
parse_coordinate("95.0", coord_type="latitude") # Raises ValueError
# Longitude validation (-180 to 180)
parse_coordinate("120.5", coord_type="longitude") # Valid
parse_coordinate("185.0", coord_type="longitude") # Raises ValueError
# Disable validation
parse_coordinate("95.0", coord_type="latitude", validate=False) # Returns 95.0
```
## Error Handling
The library provides comprehensive error handling:
```python
try:
coord = parse_coordinate("invalid_coordinate")
except ValueError as e:
print(f"Parse error: {e}")
# Common error cases:
# - Invalid format: "'invalid' is not a valid coordinate string"
# - Out of range: "Latitude 95.0 is outside valid range [-90, 90]"
# - Invalid minutes: "Minutes 65 must be less than 60"
# - Invalid seconds: "Seconds 75 must be less than 60"
```
## Development
### Setup Development Environment
```bash
git clone https://github.com/shipster-ai/coordinate-parser.git
cd coordinate-parser
pip install -e ".[dev]"
```
### Running Tests
```bash
pytest
```
### Running Tests with Coverage
```bash
pytest --cov=coordinate_parser --cov-report=html
```
### Code Quality
```bash
# Format code
black src/ tests/
# Lint code
ruff check src/ tests/
# Type checking
mypy src/
```
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.
1. Fork the repository
2. Create your feature branch (`git checkout -b feature/AmazingFeature`)
3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)
4. Push to the branch (`git push origin feature/AmazingFeature`)
5. Open a Pull Request
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## Credits
Originally developed as part of the Shipster project for parsing maritime coordinates.
Raw data
{
"_id": null,
"home_page": null,
"name": "coordinate-parser",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": "Samantha Swift <s.swift@marcura.com>",
"keywords": "coordinates, gis, latitude, longitude, maritime, parsing",
"author": null,
"author_email": "Samantha Swift <s.swift@marcura.com>",
"download_url": "https://files.pythonhosted.org/packages/da/6c/a0fa0d0a8714aaa8a63e3bb0ae6a4e1f7ca8b5f27a619e353fba37d38285/coordinate_parser-0.1.1.tar.gz",
"platform": null,
"description": "# Coordinate Parser\n\n[](https://github.com/17swifts/coordinate-parser/actions/workflows/ci.yml)\n[](https://badge.fury.io/py/coordinate-parser)\n[](https://www.python.org/downloads/)\n\nA robust Python library for parsing geographic coordinates in various formats. This library can handle decimal degrees, degrees/minutes/seconds, and maritime coordinate formats with high precision.\n\n## Features\n\n- **Multiple format support**: Decimal degrees, degrees/minutes/seconds, maritime formats\n- **Flexible input**: Accepts strings, floats, integers, and Decimal types\n- **Validation**: Optional coordinate validation with customizable ranges\n- **High precision**: Uses Python's Decimal type for accurate calculations\n- **Maritime formats**: Special support for nautical coordinate formats\n- **Internationalization**: Supports Cyrillic cardinal directions\n- **Error handling**: Comprehensive error messages for invalid inputs\n\n## Installation\n\n```bash\npip install coordinate-parser\n```\n\n## Quick Start\n\n```python\nfrom coordinate_parser import parse_coordinate\n\n# Basic usage\nlat = parse_coordinate(\"40\u00b041.65'N\")\nlon = parse_coordinate(\"74\u00b002.54'W\")\nprint(f\"Latitude: {lat}, Longitude: {lon}\")\n\n# Decimal degrees\ncoord = parse_coordinate(\"23.43\")\nprint(f\"Coordinate: {coord}\")\n\n# With validation\nlat = parse_coordinate(\"45.5\", coord_type=\"latitude\")\nlon = parse_coordinate(\"120.5\", coord_type=\"longitude\")\n```\n\n## Supported Formats\n\n### Decimal Degrees\n\n```python\nparse_coordinate(\"23.43\") # 23.43\nparse_coordinate(\"-45.21\") # -45.21\nparse_coordinate(\"23.43 N\") # 23.43\nparse_coordinate(\"45.21 W\") # -45.21\n```\n\n### Degrees and Minutes\n\n```python\nparse_coordinate(\"23\u00b0 25.800'\") # 23.43\nparse_coordinate(\"23 25.8 N\") # 23.43\nparse_coordinate(\"45\u00b012.6'S\") # -45.21\n```\n\n### Degrees, Minutes, and Seconds\n\n```python\nparse_coordinate(\"23\u00b0 25' 48.0\\\" N\") # 23.43\nparse_coordinate(\"45\u00b0 12' 36.0\\\" S\") # -45.21\nparse_coordinate(\"23d 25m 48s\") # 23.43\n```\n\n### Maritime Formats\n\n```python\n# Pattern 1: degree-dash-minutes with degree symbol\nparse_coordinate(\"40\u00b0\u201341.65'N\") # 40.694166666667\nparse_coordinate(\"139\u00b0-02.54'E\") # 139.042333333333\n\n# Pattern 2: degree-dash-minutes without degree symbol\nparse_coordinate(\"54-05.48N\") # 54.091333333333\nparse_coordinate(\"162-29.03W\") # -162.483833333333\n\n# Pattern 3: degree-minutes with degree symbol\nparse_coordinate(\"30\u00b034.4'N\") # 30.573333333333\nparse_coordinate(\"120\u00b045.5'E\") # 120.758333333333\n\n# Pattern 4: degree-minutes-seconds\nparse_coordinate(\"30\u00b034'24.0\\\"N\") # 30.573333333333\n```\n\n### International Support\n\n```python\n# Cyrillic cardinal directions\nparse_coordinate(\"23.43 \u0421\") # North (\u0421 = N)\nparse_coordinate(\"45.21 \u0417\") # West (\u0417 = W)\nparse_coordinate(\"23.43 \u0412\") # East (\u0412 = E)\nparse_coordinate(\"45.21 \u042e\") # South (\u042e = S)\n\n# Comma as decimal separator\nparse_coordinate(\"23,43\") # 23.43\nparse_coordinate(\"23\u00b0 25,8'\") # 23.43\n```\n\n## API Reference\n\n### `parse_coordinate(string, coord_type=\"coordinate\", validate=True)`\n\nParse a coordinate string and return a Decimal value in decimal degrees.\n\n**Parameters:**\n\n- `string` (str | float | Decimal | None): The coordinate to parse\n- `coord_type` (str): Type of coordinate for validation (\"latitude\", \"longitude\", or \"coordinate\")\n- `validate` (bool): Whether to validate the coordinate is within valid ranges\n\n**Returns:**\n\n- `Decimal | None`: The parsed coordinate in decimal degrees, or None if input is None/empty\n\n**Raises:**\n\n- `ValueError`: If the coordinate cannot be parsed or is outside valid range\n\n### `to_dec_deg(*args)`\n\nConvert degrees, minutes, seconds to decimal degrees.\n\n**Parameters:**\n\n- `*args`: Variable arguments representing degrees, minutes (optional), seconds (optional)\n\n**Returns:**\n\n- `float`: Decimal degrees\n\n## Validation\n\nThe library supports optional validation for coordinates:\n\n```python\n# Latitude validation (-90 to 90)\nparse_coordinate(\"45.5\", coord_type=\"latitude\") # Valid\nparse_coordinate(\"95.0\", coord_type=\"latitude\") # Raises ValueError\n\n# Longitude validation (-180 to 180)\nparse_coordinate(\"120.5\", coord_type=\"longitude\") # Valid\nparse_coordinate(\"185.0\", coord_type=\"longitude\") # Raises ValueError\n\n# Disable validation\nparse_coordinate(\"95.0\", coord_type=\"latitude\", validate=False) # Returns 95.0\n```\n\n## Error Handling\n\nThe library provides comprehensive error handling:\n\n```python\ntry:\n coord = parse_coordinate(\"invalid_coordinate\")\nexcept ValueError as e:\n print(f\"Parse error: {e}\")\n\n# Common error cases:\n# - Invalid format: \"'invalid' is not a valid coordinate string\"\n# - Out of range: \"Latitude 95.0 is outside valid range [-90, 90]\"\n# - Invalid minutes: \"Minutes 65 must be less than 60\"\n# - Invalid seconds: \"Seconds 75 must be less than 60\"\n```\n\n## Development\n\n### Setup Development Environment\n\n```bash\ngit clone https://github.com/shipster-ai/coordinate-parser.git\ncd coordinate-parser\npip install -e \".[dev]\"\n```\n\n### Running Tests\n\n```bash\npytest\n```\n\n### Running Tests with Coverage\n\n```bash\npytest --cov=coordinate_parser --cov-report=html\n```\n\n### Code Quality\n\n```bash\n# Format code\nblack src/ tests/\n\n# Lint code\nruff check src/ tests/\n\n# Type checking\nmypy src/\n```\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/AmazingFeature`)\n3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)\n4. Push to the branch (`git push origin feature/AmazingFeature`)\n5. Open a Pull Request\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Credits\n\nOriginally developed as part of the Shipster project for parsing maritime coordinates.\n",
"bugtrack_url": null,
"license": null,
"summary": "A Python library for parsing geographic coordinates in various formats",
"version": "0.1.1",
"project_urls": {
"Documentation": "https://github.com/17swifts/coordinate-parser#readme",
"Homepage": "https://github.com/17swifts/coordinate-parser",
"Issues": "https://github.com/17swifts/coordinate-parser/issues",
"Repository": "https://github.com/17swifts/coordinate-parser"
},
"split_keywords": [
"coordinates",
" gis",
" latitude",
" longitude",
" maritime",
" parsing"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "c9579ed1c25333314059b4ac201199f2364253cb362a999fd3613a295f0979f2",
"md5": "78087e4a2b7c02a485434cb35dec0ef4",
"sha256": "864c2304a059fc32af7e47733412aa0a7e2fba24aeec7cde3ad58d6efca60fbe"
},
"downloads": -1,
"filename": "coordinate_parser-0.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "78087e4a2b7c02a485434cb35dec0ef4",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 7653,
"upload_time": "2025-09-17T11:30:48",
"upload_time_iso_8601": "2025-09-17T11:30:48.878267Z",
"url": "https://files.pythonhosted.org/packages/c9/57/9ed1c25333314059b4ac201199f2364253cb362a999fd3613a295f0979f2/coordinate_parser-0.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "da6ca0fa0d0a8714aaa8a63e3bb0ae6a4e1f7ca8b5f27a619e353fba37d38285",
"md5": "100f966189c95a56897a8184b2a7ed24",
"sha256": "f94b90dc656fa571c046ac3364cda450474df836525cefc40b1fa421e14e24e6"
},
"downloads": -1,
"filename": "coordinate_parser-0.1.1.tar.gz",
"has_sig": false,
"md5_digest": "100f966189c95a56897a8184b2a7ed24",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 9037,
"upload_time": "2025-09-17T11:30:50",
"upload_time_iso_8601": "2025-09-17T11:30:50.500541Z",
"url": "https://files.pythonhosted.org/packages/da/6c/a0fa0d0a8714aaa8a63e3bb0ae6a4e1f7ca8b5f27a619e353fba37d38285/coordinate_parser-0.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-17 11:30:50",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "17swifts",
"github_project": "coordinate-parser#readme",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "coordinate-parser"
}
JSON
