{"openapi":"3.1.0","info":{"title":"REST API Mapy.com geocoding methods","description":"Get coordinates and location for given geographic entity (e.g. address, city, WGS coordinates)","version":"1.0.0"},"paths":{"/v1/rgeocode":{"get":{"tags":["geocoding"],"summary":"Get regional entities for coordinates","description":"Reverse geocode - get regional entities for given location coordinates. Rate limit is 200 requests per second per API key. Rate limit 100 requests per second per API key.","operationId":"api_rgeocode_v1_rgeocode_get","parameters":[{"description":"Location longitude in degrees (decimal point is \".\"). Positive means east, negative west.","required":true,"schema":{"type":"number","maximum":180.0,"minimum":-180.0,"title":"Location longitude","description":"Location longitude in degrees (decimal point is \".\"). Positive means east, negative west."},"example":14.42212,"name":"lon","in":"query"},{"description":"Location latitude in degrees (decimal point is \".\"). Positive means north, negative south.","required":true,"schema":{"type":"number","maximum":90.0,"minimum":-90.0,"title":"Location latitude ","description":"Location latitude in degrees (decimal point is \".\"). Positive means north, negative south."},"example":50.08861,"name":"lat","in":"query"},{"description":"Preferred language for result entity names","required":false,"schema":{"allOf":[{"$ref":"#/components/schemas/Language"}],"description":"Preferred language for result entity names","default":"cs"},"name":"lang","in":"query"}],"responses":{"200":{"description":"Request succeeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RgeocodeResult"}}}},"500":{"description":"Internal Server Error"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/geocode":{"get":{"tags":["geocoding"],"summary":"Find entities for given search query","description":"Obtains coordinates and additional information (like surrounding regional structure) based on textual location query (addresses, streets, cities, ...). Rate limit is 100 requests per second per API key","operationId":"api_geocode_v1_geocode_get","parameters":[{"description":"Geographic entity name or coordinates to resolve.","required":false,"schema":{"type":"string","maxLength":150,"title":"Query","description":"Geographic entity name or coordinates to resolve.","default":""},"example":"Praha","name":"query","in":"query"},{"description":"Preferred language for result entity names","required":false,"schema":{"allOf":[{"$ref":"#/components/schemas/Language"}],"description":"Preferred language for result entity names","default":"cs"},"name":"lang","in":"query"},{"description":"Maximum number of results (default 5, upper limit 15)","required":false,"schema":{"type":"integer","exclusiveMaximum":16.0,"title":"Limit","description":"Maximum number of results (default 5, upper limit 15)","default":5},"name":"limit","in":"query"},{"description":"Return selected entity types only","required":false,"schema":{"items":{"$ref":"#/components/schemas/GeocodeEntityType"},"type":"array","description":"Return selected entity types only","default":["regional","poi"]},"name":"type","in":"query"},{"description":"Return results only from these localities.\nIt may be in form of comma-separated locality names (e. g. `Praha 5`, `Lhota u Kolína`), country codes (cz, gb, us, ...)\nor rectangles `BOX({minLon},{minLat},{maxLon},{maxLat})` or a mix of them.\nLocation names (except country codes) are internally converted to bounding boxes,\nso using box arguments is preferred to avoid ambiguities - resolved boxes for locality names are returned in response\n(or \"Not found!\" for unknown localities) to help with this. On the other hand, country codes are preferred over their\nbounding boxes, because they allow precise filtering and avoid edge-cases near the date-line.\n","required":false,"schema":{"items":{"type":"string","pattern":"BOX\\(([+-]?\\d*(.\\d*)?,){3}[+-]?\\d*(.\\d*)?\\)|^(?!BOX\\().*"},"type":"array","pattern":"BOX\\(([+-]?\\d*(.\\d*)?,){3}[+-]?\\d*(.\\d*)?\\)|^(?!BOX\\().*","title":"Locality","description":"Return results only from these localities.\nIt may be in form of comma-separated locality names (e. g. `Praha 5`, `Lhota u Kolína`), country codes (cz, gb, us, ...)\nor rectangles `BOX({minLon},{minLat},{maxLon},{maxLat})` or a mix of them.\nLocation names (except country codes) are internally converted to bounding boxes,\nso using box arguments is preferred to avoid ambiguities - resolved boxes for locality names are returned in response\n(or \"Not found!\" for unknown localities) to help with this. On the other hand, country codes are preferred over their\nbounding boxes, because they allow precise filtering and avoid edge-cases near the date-line.\n"},"name":"locality","in":"query"},{"description":"Prefer results from this box (not a filter). Conflicts with `near`. If neither `box` nor `near` is specified, defaults to envelope over all regions provided via `locality` query argument, Czech Republic otherwise. Format `{minLon},{minLat},{maxLon},{maxLat}` If specified together with the `locality` argument, it must intersect at least one of the `locality` areas.","required":false,"schema":{"items":{"type":"number"},"type":"array","maxItems":4,"minItems":4,"title":"Preferbbox","description":"Prefer results from this box (not a filter). Conflicts with `near`. If neither `box` nor `near` is specified, defaults to envelope over all regions provided via `locality` query argument, Czech Republic otherwise. Format `{minLon},{minLat},{maxLon},{maxLat}` If specified together with the `locality` argument, it must intersect at least one of the `locality` areas."},"name":"preferBBox","in":"query"},{"description":"Prefer results near this position (not a filter). Conflicts with `box`. Format `{lon},{lat}` If specified together with the `locality` argument, it must be within at least one of the `locality` areas.","required":false,"schema":{"items":{"type":"number"},"type":"array","maxItems":2,"minItems":2,"title":"Prefernear","description":"Prefer results near this position (not a filter). Conflicts with `box`. Format `{lon},{lat}` If specified together with the `locality` argument, it must be within at least one of the `locality` areas."},"name":"preferNear","in":"query"},{"description":"Precision of parameter `near` in meters (use to prefer results from a circle)","required":false,"schema":{"type":"number","minimum":0.0,"title":"Prefernearprecision","description":"Precision of parameter `near` in meters (use to prefer results from a circle)"},"name":"preferNearPrecision","in":"query"}],"responses":{"200":{"description":"Request succeeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GeocodeResult"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/suggest":{"get":{"tags":["geocoding"],"summary":"Suggest entities while typing a query","description":"Suggest works similarly to geocoding, but it accounts for incomplete queries, so it can be used to suggest matching entities while user is writing the location query. Rate limit is 100 requests per second per API key","operationId":"api_suggest_v1_suggest_get","parameters":[{"description":"Geographic entity name or coordinates to resolve.","required":false,"schema":{"type":"string","maxLength":150,"title":"Query","description":"Geographic entity name or coordinates to resolve.","default":""},"example":"Praha","name":"query","in":"query"},{"description":"Preferred language for result entity names","required":false,"schema":{"allOf":[{"$ref":"#/components/schemas/Language"}],"description":"Preferred language for result entity names","default":"cs"},"name":"lang","in":"query"},{"description":"Maximum number of results (default 5, upper limit 15)","required":false,"schema":{"type":"integer","exclusiveMaximum":16.0,"title":"Limit","description":"Maximum number of results (default 5, upper limit 15)","default":5},"name":"limit","in":"query"},{"description":"Return selected entity types only","required":false,"schema":{"items":{"$ref":"#/components/schemas/GeocodeEntityType"},"type":"array","description":"Return selected entity types only","default":["regional","poi"]},"name":"type","in":"query"},{"description":"Return results only from these localities.\nIt may be in form of comma-separated locality names (e. g. `Praha 5`, `Lhota u Kolína`), country codes (cz, gb, us, ...)\nor rectangles `BOX({minLon},{minLat},{maxLon},{maxLat})` or a mix of them.\nLocation names (except country codes) are internally converted to bounding boxes,\nso using box arguments is preferred to avoid ambiguities - resolved boxes for locality names are returned in response\n(or \"Not found!\" for unknown localities) to help with this. On the other hand, country codes are preferred over their\nbounding boxes, because they allow precise filtering and avoid edge-cases near the date-line.\n","required":false,"schema":{"items":{"type":"string","pattern":"BOX\\(([+-]?\\d*(.\\d*)?,){3}[+-]?\\d*(.\\d*)?\\)|^(?!BOX\\().*"},"type":"array","pattern":"BOX\\(([+-]?\\d*(.\\d*)?,){3}[+-]?\\d*(.\\d*)?\\)|^(?!BOX\\().*","title":"Locality","description":"Return results only from these localities.\nIt may be in form of comma-separated locality names (e. g. `Praha 5`, `Lhota u Kolína`), country codes (cz, gb, us, ...)\nor rectangles `BOX({minLon},{minLat},{maxLon},{maxLat})` or a mix of them.\nLocation names (except country codes) are internally converted to bounding boxes,\nso using box arguments is preferred to avoid ambiguities - resolved boxes for locality names are returned in response\n(or \"Not found!\" for unknown localities) to help with this. On the other hand, country codes are preferred over their\nbounding boxes, because they allow precise filtering and avoid edge-cases near the date-line.\n"},"name":"locality","in":"query"},{"description":"Prefer results from this box (not a filter). Conflicts with `near`. If neither `box` nor `near` is specified, defaults to envelope over all regions provided via `locality` query argument, Czech Republic otherwise. Format `{minLon},{minLat},{maxLon},{maxLat}` If specified together with the `locality` argument, it must intersect at least one of the `locality` areas.","required":false,"schema":{"items":{"type":"number"},"type":"array","maxItems":4,"minItems":4,"title":"Preferbbox","description":"Prefer results from this box (not a filter). Conflicts with `near`. If neither `box` nor `near` is specified, defaults to envelope over all regions provided via `locality` query argument, Czech Republic otherwise. Format `{minLon},{minLat},{maxLon},{maxLat}` If specified together with the `locality` argument, it must intersect at least one of the `locality` areas."},"name":"preferBBox","in":"query"},{"description":"Prefer results near this position (not a filter). Conflicts with `box`. Format `{lon},{lat}` If specified together with the `locality` argument, it must be within at least one of the `locality` areas.","required":false,"schema":{"items":{"type":"number"},"type":"array","maxItems":2,"minItems":2,"title":"Prefernear","description":"Prefer results near this position (not a filter). Conflicts with `box`. Format `{lon},{lat}` If specified together with the `locality` argument, it must be within at least one of the `locality` areas."},"name":"preferNear","in":"query"},{"description":"Precision of parameter `near` in meters (use to prefer results from a circle)","required":false,"schema":{"type":"number","minimum":0.0,"title":"Prefernearprecision","description":"Precision of parameter `near` in meters (use to prefer results from a circle)"},"name":"preferNearPrecision","in":"query"}],"responses":{"200":{"description":"Request succeeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GeocodeResult"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"Coordinates":{"properties":{"lon":{"type":"number","maximum":180.0,"minimum":-180.0,"title":"Location longitude","description":"Location longitude in degrees (decimal point is \".\"). Positive means east, negative west.","example":14.42212},"lat":{"type":"number","maximum":90.0,"minimum":-90.0,"title":"Location latitude ","description":"Location latitude in degrees (decimal point is \".\"). Positive means north, negative south.","example":50.08861}},"type":"object","required":["lon","lat"],"title":"Coordinates"},"GeocodeEntityType":{"type":"string","enum":["regional","regional.country","regional.region","regional.municipality","regional.municipality_part","regional.street","regional.address","poi","coordinate"],"title":"GeocodeEntityType","description":"An enumeration."},"GeocodeResult":{"properties":{"items":{"items":{"$ref":"#/components/schemas/GeocodeResultEntity"},"type":"array","title":"Items"},"locality":{"items":{"type":"object"},"type":"array","title":"Locality","description":"Bboxes for localities used in param `locality`","default":[]}},"type":"object","required":["items"],"title":"GeocodeResult","description":"Ordered list of matching geographical entities","example":{"items":[{"name":"Týnská ulička 610/7","label":"Adresa","position":{"lon":14.42212,"lat":50.08861},"type":"regional.address","location":"Praha 1 - Staré Město, Česko","regionalStructure":[{"name":"610/7","type":"regional.address"},{"name":"Týnská ulička","type":"regional.street"},{"name":"Staré město 1","type":"regional.municipality_part"},{"name":"Praha 1","type":"regional.municipality_part"},{"name":"Praha","type":"regional.municipality"},{"name":"Okres Hlavní město Praha","type":"regional.region"},{"name":"Hlavní město Praha","type":"regional.region"},{"name":"Česko","type":"regional.country","isoCode":"CZ"}],"zip":"15000","bbox":[14.2244367599487,49.9418983459473,14.706787109375,50.1774291992188]}],"locality":[{"Brno":"BOX(16.428,49.1099,16.7278,49.2944)"},{"Praha":"BOX(14.2244,49.9419,14.7068,50.1774)"}]}},"GeocodeResultEntity":{"properties":{"name":{"type":"string","title":"Name","example":"Praha"},"label":{"type":"string","title":"Label","example":"Hlavní město"},"position":{"$ref":"#/components/schemas/Coordinates"},"bbox":{"items":{"type":"number"},"type":"array","maxItems":4,"minItems":4,"title":"Bbox"},"type":{"allOf":[{"$ref":"#/components/schemas/GeocodeEntityType"}],"example":"poi"},"location":{"type":"string","title":"Location","description":"Short label for locality of resolved entity","example":"Praha 1 - Staré Město, Česko"},"regionalStructure":{"items":{"$ref":"#/components/schemas/RegionalEntity"},"type":"array","minItems":1,"title":"Regionalstructure","description":"Ordered list of parent administrative entities (smallest first)."},"zip":{"type":"string","title":"Zip","description":"Postal code, available only in some areas and only for entity type `reg_address`)"}},"type":"object","required":["name","label","position","type","regionalStructure"],"title":"GeocodeResultEntity"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"Language":{"type":"string","enum":["cs","de","el","en","es","fr","it","nl","pl","pt","ru","sk","tr","uk"],"title":"Language","description":"An enumeration."},"RegionalEntity":{"properties":{"name":{"type":"string","title":"Name"},"type":{"$ref":"#/components/schemas/GeocodeEntityType"},"isoCode":{"type":"string","title":"Isocode","description":"Iso code by ISO 3166-1 alpha-2, only for regional.country"}},"type":"object","required":["name","type"],"title":"RegionalEntity"},"RgeoEntityType":{"type":"string","enum":["regional","regional.country","regional.region","regional.municipality","regional.municipality_part","regional.street","regional.address"],"title":"RgeoEntityType","description":"An enumeration."},"RgeocodeResult":{"properties":{"items":{"items":{"$ref":"#/components/schemas/RgeocodeResultEntity"},"type":"array","title":"Items"}},"type":"object","required":["items"],"title":"RgeocodeResult","example":{"items":[{"name":"Týnská ulička 610/7","label":"Adresa","position":{"lon":14.42212,"lat":50.08861},"type":"regional.address","location":"Praha 1 - Staré Město, Česko","regionalStructure":[{"name":"610/7","type":"regional.address"},{"name":"Týnská ulička","type":"regional.street"},{"name":"Staré město 1","type":"regional.municipality_part"},{"name":"Praha 1","type":"regional.municipality_part"},{"name":"Praha","type":"regional.municipality"},{"name":"Okres Hlavní město Praha","type":"regional.region"},{"name":"Hlavní město Praha","type":"regional.region"},{"name":"Česko","type":"regional.country","isoCode":"CZ"}],"zip":"15000","bbox":[14.2244367599487,49.9418983459473,14.706787109375,50.1774291992188]}]}},"RgeocodeResultEntity":{"properties":{"name":{"type":"string","title":"Name","example":"Praha"},"label":{"type":"string","title":"Label","example":"Hlavní město"},"position":{"$ref":"#/components/schemas/Coordinates"},"bbox":{"items":{"type":"number"},"type":"array","maxItems":4,"minItems":4,"title":"Bbox"},"type":{"allOf":[{"$ref":"#/components/schemas/RgeoEntityType"}],"example":"regional.municipality"},"location":{"type":"string","title":"Location","description":"Short label for locality of resolved entity","example":"Praha 1 - Staré Město, Česko"},"regionalStructure":{"items":{"$ref":"#/components/schemas/RegionalEntity"},"type":"array","minItems":1,"title":"Regionalstructure","description":"Ordered list of parent administrative entities (smallest first)."},"zip":{"type":"string","title":"Zip","description":"Postal code, available only in some areas and only for entity type `reg_address`)"}},"type":"object","required":["name","label","position","type","regionalStructure"],"title":"RgeocodeResultEntity"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}},"securitySchemes":{"headerApiKey":{"type":"apiKey","in":"header","name":"X-Mapy-Api-Key"},"queryApiKey":{"type":"apiKey","in":"query","name":"apikey"}}},"servers":[{"url":"https://api.mapy.com/"},{"url":"https://api.mapy.cz/"}],"security":[{"queryApiKey":[]},{"headerApiKey":[]}]}