{"id":28825656,"url":"https://github.com/iwatkot/maps4fsapi","last_synced_at":"2026-04-02T19:12:58.858Z","repository":{"id":298258341,"uuid":"999337525","full_name":"iwatkot/maps4fsapi","owner":"iwatkot","description":"API for maps4fs, the tool that allows to generate map templates for Farming Simulator from real places.","archived":false,"fork":false,"pushed_at":"2026-03-30T23:21:53.000Z","size":181,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-31T01:34:56.742Z","etag":null,"topics":["api","farming-simulator","farmingsimulator","fastapi","fs22","fs25","maps4fs","rest-api"],"latest_commit_sha":null,"homepage":"https://api.maps4fs.xyz","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/iwatkot.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-06-10T05:28:28.000Z","updated_at":"2026-03-12T18:29:54.000Z","dependencies_parsed_at":"2025-06-10T07:35:26.306Z","dependency_job_id":"56063127-206c-43a7-8ff6-9a23831b2298","html_url":"https://github.com/iwatkot/maps4fsapi","commit_stats":null,"previous_names":["iwatkot/maps4fsapi"],"tags_count":129,"template":false,"template_full_name":null,"purl":"pkg:github/iwatkot/maps4fsapi","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iwatkot%2Fmaps4fsapi","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iwatkot%2Fmaps4fsapi/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iwatkot%2Fmaps4fsapi/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iwatkot%2Fmaps4fsapi/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/iwatkot","download_url":"https://codeload.github.com/iwatkot/maps4fsapi/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iwatkot%2Fmaps4fsapi/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31314125,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-02T12:59:32.332Z","status":"ssl_error","status_checked_at":"2026-04-02T12:54:48.875Z","response_time":89,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":["api","farming-simulator","farmingsimulator","fastapi","fs22","fs25","maps4fs","rest-api"],"created_at":"2025-06-19T02:05:12.743Z","updated_at":"2026-04-02T19:12:58.848Z","avatar_url":"https://github.com/iwatkot.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\" markdown\u003e\n\n[![Maps4FS](https://img.shields.io/badge/maps4fs-gray?style=for-the-badge)](https://github.com/iwatkot/maps4fs)\n[![Maps4FS](https://img.shields.io/badge/atlasfs-green?style=for-the-badge)](https://github.com/iwatkot/atlasfs)\n[![Maps4FS](https://img.shields.io/badge/maps4fs-windows-purple?style=for-the-badge)](https://github.com/iwatkot/maps4fswindows)\n[![PYDTMDL](https://img.shields.io/badge/pydtmdl-blue?style=for-the-badge)](https://github.com/iwatkot/pydtmdl)\n[![PYGDMDL](https://img.shields.io/badge/pygmdl-teal?style=for-the-badge)](https://github.com/iwatkot/pygmdl)  \n[![Maps4FS API](https://img.shields.io/badge/maps4fs-api-green?style=for-the-badge)](https://github.com/iwatkot/maps4fsapi)\n[![Maps4FS UI](https://img.shields.io/badge/maps4fs-ui-blue?style=for-the-badge)](https://github.com/iwatkot/maps4fsui)\n[![Maps4FS Data](https://img.shields.io/badge/maps4fs-data-orange?style=for-the-badge)](https://github.com/iwatkot/maps4fsdata)\n[![Maps4FS ChromaDocs](https://img.shields.io/badge/maps4fs-chromadocs-orange?style=for-the-badge)](https://github.com/iwatkot/maps4fschromadocs)  \n[![Maps4FS Upgrader](https://img.shields.io/badge/maps4fs-upgrader-yellow?style=for-the-badge)](https://github.com/iwatkot/maps4fsupgrader)\n[![Maps4FS Stats](https://img.shields.io/badge/maps4fs-stats-red?style=for-the-badge)](https://github.com/iwatkot/maps4fsstats)\n[![Maps4FS Bot](https://img.shields.io/badge/maps4fs-bot-teal?style=for-the-badge)](https://github.com/iwatkot/maps4fsbot)\n[![Maps4FS Locale](https://img.shields.io/badge/maps4fs-locale-purple?style=for-the-badge)](https://github.com/iwatkot/maps4fslocale)\n\n\u003c/div\u003e\n\n\u003cdiv align=\"center\" markdown\u003e\n\n\u003cimg src=\"https://github.com/iwatkot/maps4fsapi/releases/download/2.9.53/api-1280-640.png\"\u003e\n\n\u003cp align=\"center\"\u003e\n    \u003ca href=\"#maps4fs\"\u003eMaps4FS\u003c/a\u003e •\n    \u003ca href=\"#overview\"\u003eOverview\u003c/a\u003e •\n    \u003ca href=\"#public-and-private-apis\"\u003ePublic and Private APIs\u003c/a\u003e •\n    \u003ca href=\"#queuing\"\u003eQueuing\u003c/a\u003e •\n    \u003ca href=\"#maps4fs-api\"\u003eMaps4FS API\u003c/a\u003e\u003cbr\u003e\n    \u003ca href=\"#map-endpoints\"\u003eMap Endpoints\u003c/a\u003e •\n    \u003ca href=\"#task-endpoints\"\u003eTask Endpoints\u003c/a\u003e •\n    \u003ca href=\"#dtm-endpoints\"\u003eDTM Endpoints\u003c/a\u003e •\n    \u003ca href=\"#grle-endpoints\"\u003eGRLE Endpoints\u003c/a\u003e\u003cbr\u003e\n    \u003ca href=\"#i3d-endpoints\"\u003eI3d Endpoints\u003c/a\u003e •\n    \u003ca href=\"#mesh-endpoints\"\u003eMesh Endpoints\u003c/a\u003e •\n    \u003ca href=\"#texture-endpoints\"\u003eTexture Endpoints\u003c/a\u003e •\n    \u003ca href=\"#satellite-endpoints\"\u003eSatellite Endpoints\u003c/a\u003e\n\u003c/p\u003e\n\n[![Join Discord](https://img.shields.io/badge/join-discord-blue)](https://discord.gg/Sj5QKKyE42)\n[![GitHub release (latest SemVer)](https://img.shields.io/github/v/release/iwatkot/maps4fsapi)](https://github.com/iwatkot/maps4fs/releases)\n[![Docker Pulls](https://img.shields.io/docker/pulls/iwatkot/maps4fsapi)](https://hub.docker.com/r/iwatkot/maps4fsapi)\n[![Docker Image Size](https://img.shields.io/docker/image-size/iwatkot/maps4fsapi)](https://hub.docker.com/r/iwatkot/maps4fsapi)\n[![Docker Version](https://img.shields.io/docker/v/iwatkot/maps4fsapi)](https://hub.docker.com/r/iwatkot/maps4fsapi)\n\u003cbr\u003e\n[![GitHub issues](https://img.shields.io/github/issues/iwatkot/maps4fsapi)](https://github.com/iwatkot/maps4fsapi/issues)\n[![Checked with mypy](https://www.mypy-lang.org/static/mypy_badge.svg)](https://mypy-lang.org/)\n[![Build Status](https://github.com/iwatkot/maps4fsapi/actions/workflows/checks.yml/badge.svg)](https://github.com/iwatkot/maps4fsapi/actions)\n[![GitHub Repo stars](https://img.shields.io/github/stars/iwatkot/maps4fsapi)](https://github.com/iwatkot/maps4fsapi/stargazers)\n\n\u003c/div\u003e\n\n# Maps4FS\n\nMaps4FS is a tool for automatic generation maps for Farming Simulator games using the real world data. More information can be found in the [main repository](https://github.com/iwatkot/maps4fs).  \n\nThis repository contains the source code for the Maps4FS API, based on the `fastapi` framework.\n\n# Overview\n\nThis repository is a part of the Maps4FS project, which consists of several components: the main maps4fs Python library, the maps4fs UI, the maps4fs API, the maps4fs stats, and the maps4fs bot.\n\nPlease, refer to the main repository for all the relevant information about the Maps4FS project, including the documentation.\n\n➡️ The example of using the Maps4FS API from the Python code can be found in the [demo.py](demo.py) file in the root directory of this repository.\n\n# Public and private APIs\nThe public API is available at [https://api.maps4fs.xyz](https://api.maps4fs.xyz) and provides access to the Maps4FS functionality. It requires authentication via an API key, which can be obtained in the Maps4FS Discord server by asking the bot for an API key. The API key is required for all requests to the public API.  \nThe public version of the API also has a rate limit, which can be changed at any time but for the moment is set to 10 requests per hour for the same API key.  \n\u003cbr\u003e\nThe private API will be automatically deployed in the Docker version of the Maps4FS and by default will be available at `http://localhost:8000`. It does not require an API key and does not have a rate limit.\n\n## Public API Authentication\nTo authenticate with the public API, you need to include your API key as a bearer token in the `Authorization` header of your request.  \nRequest example:\n```bash\ncurl -X POST \"http://localhost:8000/dtm/list\" \\\n  -H \"Authorization: Bearer YOUR_API_KEY_HERE\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"lat\": 10.0, \"lon\": 25.0}'\n```\n\n**NOTE:** The private API (which deployed locally) does not require an API key, so you can omit the `Authorization` header in your requests.\n\n# Queuing\nSome endpoints of the Maps4FS API will take a long time to process the request, in this case the API will validate the initial request and return a `task_id` that can be used later to retrieve the result of the request.\nThe endpoints that support queuing are marked with a ✅ in the table below. You can use the `/tasks/get` endpoint to check the status of the task and retrieve the result when it is ready.\n\nResponse example:\n```json\n{\n    \"success\": true,\n    \"description\": \"Task has been added to the queue. Use the task ID to retrieve the result.\",\n    \"task_id\": \"1234567890abcdef1234567890abcdef\"\n}\n```\n\n# Maps4FS API\nThe Maps4FS API is a RESTful API that provides access to the Maps4FS functionality. It allows you to generate maps, retrieve information about the specific components of the maps, and perform other operations related to the Maps4FS project.  \nSource documentation for the Maps4FS API is available [here](maps4fsapi/components/).  \nPydantic models from the main `maps4fs` library can be found [here](https://github.com/iwatkot/maps4fs/blob/main/maps4fs/generator/settings.py).\n\n## Map Endpoints\nThe Map component of the Maps4FS API is responsible for generating a complete map, not a single component of it. You can provide all the settings in one place and receive a `zip` archive containing all the generated files.\n\n| Method | Endpoint | Payload Model | Queuing |\n|--------|----------|---------------|--------|\n| POST   | `/map/generate` | [MapGenerationPayload](maps4fsapi/components/models.py) | ✅ |\n\n`/map/generate`: Generates a complete map based on the provided settings. The response will be a `zip` archive containing all the generated files, including DTM, GRLE, I3D, Mesh, Texture, and Satellite data.\n\n## Task Endpoints\nThose endpoints are used to obtain the data about the task previously created by any endpoint which uses queuing. You can use the `task_id` to check the status of the task and retrieve the result when it is ready.\n\n| Method | Endpoint | Payload Model | Queuing |\n|--------|----------|---------------|--------|\n| GET    | `/task/get` | [TaskIdPayload](maps4fsapi/components/models.py) | ❌ |\n\n`/task/get`: If the task completed successfully, it will return the requested data, otherwise it will return the error message with details about the error.\n\nIf the response will have OK status, in most of the cases it will return a file object.\n\n## DTM Endpoints\nThe DTM (Digital Terrain Model) component of the Maps4FS API is responsible for generating and managing the terrain data for the maps. It provides endpoints to obtain information about available DTM providers and to generate the DEM (Digital Elevation Model) for a specific area.\n\n| Method | Endpoint | Payload Model | Queuing |\n|--------|----------|---------------|--------|\n| POST   | `/dtm/list` | [LatLonPayload](maps4fsapi/components/models.py) | ❌ |\n| POST   | `/dtm/info` | [DTMCodePayload](maps4fsapi/components/models.py) | ❌ |\n| POST   | `/dtm/dem` | [DEMSettingsPayload](maps4fsapi/components/models.py) | ✅ |\n\n`/dtm/list`: Returns a list of available DTM providers for provide latitude and longitude.  \n\nResponse example:\n\n```json\n{\"srtm30\": \"🌎 Global [30.0 m/px] SRTM 30 m\"}\n```\nIn this example the `srtm30` key is a DTM provider code, that can be used in other endpoints, and the value is a human-readable description of the DTM provider.\n\n`/dtm/info`: Returns information about a specific DTM provider by provided DTM Provider code.  \n\nResponse example:\n\n```json\n{\"valid\": true, \"provider\": \"🌎 Global [30.0 m/px] SRTM 30 m\"}\n```\nIf the provided DTM code was correct, the `valid` field will be `true`, otherwise it will be `false`. The `provider` field contains a human-readable description of the DTM provider.\n\n`/dtm/dem`: Generates a DEM for a specific area defined by the provided payload.  \n\n## GRLE Endpoints\nThe GRLE component of the Maps4FS API is responsible for generating and managing the ground layer data for the maps, for example plants and farmlands.\n\n| Method | Endpoint | Payload Model | Queuing |\n|--------|----------|---------------|--------|\n| POST   | `/grle/plants` | [GRLESettingsPayload](maps4fsapi/components/models.py) | ✅ |\n| POST   | `/grle/farmlands` | [GRLESettingsPayload](maps4fsapi/components/models.py) | ✅ |\n\n`/grle/plants`: Generates a PNG file for the plants layer based on the provided settings.  \n`/grle/farmlands`: Generates a PNG file for the farmlands layer based on the provided settings.  \n\n## I3d Endpoints\nThe I3d component of the Maps4FS API is responsible for generating and managing the entities related to the I3d files, which contain trees, fields and splines.\n\n| Method | Endpoint | Payload Model | Queuing |\n|--------|----------|---------------|--------|\n| POST   | `/i3d/forests` | [I3DSettingsPayload](maps4fsapi/components/models.py) | ✅ |\n| POST   | `/i3d/fields` | [I3DSettingsPayload](maps4fsapi/components/models.py) | ✅ |\n| POST   | `/i3d/splines` | [I3DSettingsPayload](maps4fsapi/components/models.py) | ✅ |\n\n`/i3d/forests`: Returns map i3d file which contains tree data. \n`/i3d/fields`: Returns map i3d file which contains field data.\n`/i3d/splines`: Returns map i3d file which contains splines.\n\n## Mesh Endpoints\nThe Mesh component of the Maps4FS API is responsible for generating and managing the mesh data for the background terrain and the water resources. The returned files are in the `.obj` format, which can be used in various 3D applications (e.g., Blender).\n\n| Method | Endpoint | Payload Model | Queuing |\n|--------|----------|---------------|--------|\n| POST   | `/mesh/background` | [BackgroundSettingsPayload](maps4fsapi/components/models.py) | ✅ |\n| POST   | `/mesh/water` | [WaterSettingsPayload](maps4fsapi/components/models.py) | ✅ |\n\n`/mesh/background`: Returns the background mesh in the `.obj` format based on the provided settings.  \n`/mesh/water`: Returns the water mesh in the `.obj` format based on the provided settings.\n\n## Texture Endpoints\nThe Texture component of the Maps4FS API is responsible for generating weight files for different in-game textures. The returned files are in the `.png` format.\n\n| Method | Endpoint | Payload Model | Queuing |\n|--------|----------|---------------|--------|\n| POST   | `/texture/images` | [TextureSettingsPayload](maps4fsapi/components/models.py) | ✅ |\n\n`/texture/images`: Based on the provided list of `layer_names` which correspond to the `texture-schema.json` file, this endpoint can return a single `.png` file or a `zip` archive containing multiple `.png` files.\n\n## Satellite Endpoints\nThe Satellite component of the Maps4FS API is responsible for generating satellite images for the specified area. The returned files are in the `.png` format.\n\n| Method | Endpoint | Payload Model | Queuing |\n|--------|----------|---------------|--------|\n| POST   | `/satellite/overview` | [SatelliteSettingsPayload](maps4fsapi/components/models.py) | ✅ |\n| POST   | `/satellite/background` | [SatelliteSettingsPayload](maps4fsapi/components/models.py) | ✅ |\n\n`/satellite/overview`: Returns an overview satellite image for the specified area. The overview image covers twice the area of the provided map size to create an in-game overview map.\n`/satellite/background`: Returns a background satellite image for the specified area. This image can be used as a texture for the beackground terrain mesh obtained from the `/mesh/background` endpoint.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fiwatkot%2Fmaps4fsapi","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fiwatkot%2Fmaps4fsapi","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fiwatkot%2Fmaps4fsapi/lists"}