{"id":19556142,"url":"https://github.com/geovation/usemap-rest","last_synced_at":"2026-05-07T13:05:38.027Z","repository":{"id":37857207,"uuid":"491446694","full_name":"Geovation/usemap-rest","owner":"Geovation","description":"Services to support UseMap application","archived":false,"fork":false,"pushed_at":"2023-04-05T09:50:59.000Z","size":36,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-01-08T21:34:46.696Z","etag":null,"topics":["api","flask","python"],"latest_commit_sha":null,"homepage":"","language":"Python","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/Geovation.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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}},"created_at":"2022-05-12T09:25:07.000Z","updated_at":"2022-07-26T14:43:51.000Z","dependencies_parsed_at":"2024-11-11T04:37:03.596Z","dependency_job_id":"f62eb615-830b-47a1-a874-964788a4068a","html_url":"https://github.com/Geovation/usemap-rest","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Geovation%2Fusemap-rest","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Geovation%2Fusemap-rest/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Geovation%2Fusemap-rest/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Geovation%2Fusemap-rest/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Geovation","download_url":"https://codeload.github.com/Geovation/usemap-rest/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":240814837,"owners_count":19861955,"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":["api","flask","python"],"created_at":"2024-11-11T04:36:57.153Z","updated_at":"2026-05-07T13:05:37.943Z","avatar_url":"https://github.com/Geovation.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# UseMap REST services\n\nServices to support UseMap application, deployed as a Python Flask API.\n\n## Getting Started\n\nThese instructions will give you a copy of the project up and running on\nyour local machine for development and testing purposes. See deployment\nfor notes on deploying the project on a live system.\n\n## Prerequisites\n\nRequirements for the software and other tools to build, test and push. These should be installed on your local computer.\n\n- [Python 3](https://www.python.org/downloads/)\n- [Pip](https://pypi.org/project/pip/)\n- [Pipenv](https://pipenv.pypa.io/en/latest/)\n\n## Installing\n\nThe project uses a Pipfile to define dependencies. Before running, ensure the required dependencies are installed for your virtual environment.\n\n```console\npipenv install\n```\n\n## Running\n\nThe project can be run locally with the included shell file.\n\n```console\n./bootstrap.sh\n```\n\nEnsure you set your OS API key within your local environment. A copy of `.env.sample` can be taken and renamed to `.env` - the API key should be entered in that file in the `os_api_key` line.\n\nThe environment file also allows for cross origin resource sharing to be configured. Enter the value you require (e.g. `*` or `http://localhost:3000`) for the `cors_origin` variable.\n\n## API documentation\n\n### Endpoint: /features/toid/\u003ctoid\u003e\n\nReturns building information based on the Topographic Identifier (TOID)\n\n`/features/toid/\u003ctoid\u003e`\n\n| URL parameter | Description                                       |\n| ------------- | ------------------------------------------------- |\n| toid          | An Ordnance Survey TOID e.g. osgb0000045763621288 |\n\nThe returned data is a set of information about a specific building, including its geometry (shape on a map) and area in square meters\n\n```json\n{\n  \"type\": \"FeatureCollection\",\n  \"crs\": {\n    \"type\": \"name\",\n    \"properties\": {\n      \"name\": \"EPSG:4326\"\n    }\n  },\n  \"features\": [\n    {\n      \"type\": \"Feature\",\n      \"geometry\": {\n        \"type\": \"MultiPolygon\",\n        \"coordinates\": [\n          [\n            [\n              [50.93857733, -1.47089411],\n              [50.9385768, -1.4708944]\n            ]\n          ]\n        ]\n      },\n      \"properties\": {\n        \"GmlID\": \"Topography_TopographicArea.61885403\",\n        \"OBJECTID\": 61885403,\n        \"TOID\": \"osgb1000002682081995\",\n        \"Theme\": \"Buildings\",\n        \"CalculatedAreaValue\": 6871.498608,\n        \"ChangeDate\": \"5/10/2022\",\n        \"DescriptiveGroup\": \"Building\"\n      }\n    }\n  ]\n}\n```\n\n### Endpoint: /places/\u003csearch\u003e\n\nReturns place search results\n\n`/places/\u003csearch\u003e`\n\n| URL parameter | Description                          |\n| ------------- | ------------------------------------ |\n| search        | An address search term e.g. SO16 0AS |\n\nThe returned data is an array of places that match the search term, currently limited to 30 results.\n\n```json\n[\n  {\n    \"ADDRESS\": \"ORDNANCE SURVEY, 4, ADANAC DRIVE, NURSLING, SOUTHAMPTON, SO16 0AS\",\n    \"BLPU_STATE_CODE\": \"2\",\n    \"BLPU_STATE_CODE_DESCRIPTION\": \"In use\",\n    \"BLPU_STATE_DATE\": \"01/09/2010\",\n    \"BUILDING_NUMBER\": \"4\",\n    \"CLASSIFICATION_CODE\": \"CO01GV\",\n    \"CLASSIFICATION_CODE_DESCRIPTION\": \"Central Government Service\",\n    \"COUNTRY_CODE\": \"E\",\n    \"COUNTRY_CODE_DESCRIPTION\": \"This record is within England\",\n    \"DELIVERY_POINT_SUFFIX\": \"1A\",\n    \"DEPENDENT_LOCALITY\": \"NURSLING\",\n    \"ENTRY_DATE\": \"01/09/2010\",\n    \"LANGUAGE\": \"EN\",\n    \"LAST_UPDATE_DATE\": \"31/03/2020\",\n    \"LOCAL_CUSTODIAN_CODE\": 1760,\n    \"LOCAL_CUSTODIAN_CODE_DESCRIPTION\": \"TEST VALLEY\",\n    \"LOGICAL_STATUS_CODE\": \"1\",\n    \"MATCH\": 1.0,\n    \"MATCH_DESCRIPTION\": \"EXACT\",\n    \"ORGANISATION_NAME\": \"ORDNANCE SURVEY\",\n    \"POSTAL_ADDRESS_CODE\": \"D\",\n    \"POSTAL_ADDRESS_CODE_DESCRIPTION\": \"A record which is linked to PAF\",\n    \"POSTCODE\": \"SO16 0AS\",\n    \"POST_TOWN\": \"SOUTHAMPTON\",\n    \"RPC\": \"2\",\n    \"STATUS\": \"APPROVED\",\n    \"THOROUGHFARE_NAME\": \"ADANAC DRIVE\",\n    \"TOPOGRAPHY_LAYER_TOID\": \"osgb1000002682081995\",\n    \"UDPRN\": \"52126562\",\n    \"UPRN\": \"200010019924\",\n    \"X_COORDINATE\": 437292.43,\n    \"Y_COORDINATE\": 115541.95\n  }\n]\n```\n\n### Endpoint: /places/toid/\u003ctoid\u003e\n\nReturns place information for a building by passing its Topographic Identifier (TOID)\n\n`/places/toid/\u003ctoid\u003e`\n\n| URL parameter | Description                                       |\n| ------------- | ------------------------------------------------- |\n| toid          | An Ordnance Survey TOID e.g. osgb0000045763621288 |\n\nReturns a format identical to the search endpoint, but uses a building's unique TOID instead of a query. To be used if a building is already known (e.g. when clicked on the map)\n\n```json\n[\n  {\n    \"UPRN\": \"200010019924\",\n    \"UDPRN\": \"52126562\",\n    \"ADDRESS\": \"ORDNANCE SURVEY, 4, ADANAC DRIVE, NURSLING, SOUTHAMPTON, SO16 0AS\",\n    \"ORGANISATION_NAME\": \"ORDNANCE SURVEY\",\n    \"BUILDING_NUMBER\": \"4\",\n    \"THOROUGHFARE_NAME\": \"ADANAC DRIVE\",\n    \"DEPENDENT_LOCALITY\": \"NURSLING\",\n    \"POST_TOWN\": \"SOUTHAMPTON\",\n    \"POSTCODE\": \"SO16 0AS\",\n    \"RPC\": \"2\",\n    \"X_COORDINATE\": 437292.43,\n    \"Y_COORDINATE\": 115541.95,\n    \"STATUS\": \"APPROVED\",\n    \"LOGICAL_STATUS_CODE\": \"1\",\n    \"CLASSIFICATION_CODE\": \"CO01GV\",\n    \"CLASSIFICATION_CODE_DESCRIPTION\": \"Central Government Service\",\n    \"LOCAL_CUSTODIAN_CODE\": 1760,\n    \"LOCAL_CUSTODIAN_CODE_DESCRIPTION\": \"TEST VALLEY\",\n    \"COUNTRY_CODE\": \"E\",\n    \"COUNTRY_CODE_DESCRIPTION\": \"This record is within England\",\n    \"POSTAL_ADDRESS_CODE\": \"D\",\n    \"POSTAL_ADDRESS_CODE_DESCRIPTION\": \"A record which is linked to PAF\",\n    \"BLPU_STATE_CODE\": \"2\",\n    \"BLPU_STATE_CODE_DESCRIPTION\": \"In use\",\n    \"TOPOGRAPHY_LAYER_TOID\": \"osgb1000002682081995\",\n    \"LAST_UPDATE_DATE\": \"31/03/2020\",\n    \"ENTRY_DATE\": \"01/09/2010\",\n    \"BLPU_STATE_DATE\": \"01/09/2010\",\n    \"LANGUAGE\": \"EN\",\n    \"MATCH\": 1.0,\n    \"MATCH_DESCRIPTION\": \"EXACT\",\n    \"DELIVERY_POINT_SUFFIX\": \"1A\"\n  }\n]\n```\n\n### Endpoint: /linkedids/uprn/\u003cuprn\u003e\n\nReturns linked ID information for a Unique Property Reference Number (UPRN)\n\n`/features/toid/\u003ctoid\u003e`\n\n| URL parameter | Description                                         |\n| ------------- | --------------------------------------------------- |\n| urpn          | A Unique Property Reference Number e.g. 10094608166 |\n\nThe returned data is a set of correlated IDs for the property\n\n```json\n{\n  \"correlations\": [\n    {\n      \"correlatedFeatureType\": \"Street\",\n      \"correlatedIdentifierType\": \"USRN\",\n      \"correlatedIdentifiers\": [\n        {\n          \"confidence\": \"Version information is correct\",\n          \"correlationIdentifier\": \"BLPU_10094608166_Street_21604971_11\",\n          \"identifier\": \"21604971\",\n          \"versionDate\": \"2016-02-10\"\n        }\n      ],\n      \"correlationMethodIdentifier\": \"BLPU_UPRN_Street_USRN_11\",\n      \"searchedIdentifierVersionDate\": \"2019-01-31\"\n    },\n    {\n      \"correlatedFeatureType\": \"RoadLink\",\n      \"correlatedIdentifierType\": \"TOID\",\n      \"correlatedIdentifiers\": [\n        {\n          \"confidence\": \"Version information is correct\",\n          \"correlationIdentifier\": \"BLPU_10094608166_RoadLink_osgb4000000030239787_9\",\n          \"identifier\": \"osgb4000000030239787\",\n          \"versionDate\": \"2017-04-15\"\n        }\n      ],\n      \"correlationMethodIdentifier\": \"BLPU_UPRN_RoadLink_TOID_9\",\n      \"searchedIdentifierVersionDate\": \"2019-01-31\"\n    },\n    {\n      \"correlatedFeatureType\": \"TopographicArea\",\n      \"correlatedIdentifierType\": \"TOID\",\n      \"correlatedIdentifiers\": [\n        {\n          \"confidence\": \"Version information is correct\",\n          \"correlationIdentifier\": \"BLPU_10094608166_TopographicArea_osgb1000005736182_5\",\n          \"identifier\": \"osgb1000005736182\",\n          \"versionDate\": \"2019-12-09\",\n          \"versionNumber\": 7\n        }\n      ],\n      \"correlationMethodIdentifier\": \"BLPU_UPRN_TopographicArea_TOID_5\",\n      \"searchedIdentifierVersionDate\": \"2019-01-31\"\n    }\n  ],\n  \"linkedIdentifier\": {\n    \"featureType\": \"BLPU\",\n    \"identifier\": \"10094608166\",\n    \"identifierType\": \"UPRN\"\n  }\n}\n```\n\n## Deployment\n\n### Development deploy to PythonAnywhere\n\n[PythonAnywhere](https://www.pythonanywhere.com/) is a service that provides easy means to host Python in the Cloud.\n\n1. Set up an account and add a new web app.\n2. Using a bash console within PythonAnywhere, `git clone` this solution to pull down the latest code.\n3. Edit the default wsgi file for your application to be the following (ensure you edit the project directory path)\n\n```python\nimport sys\nimport os\nfrom dotenv import load_dotenv\n\nproject_folder = os.path.expanduser('~/usemap-rest')  # adjust as appropriate\nload_dotenv(os.path.join(project_folder, '.env'))\n\n# add your project directory to the sys.path\nproject_home = '/home/youraccountname/usemap-rest'\nif project_home not in sys.path:\n    sys.path = [project_home] + sys.path\n\n# import flask app but need to call it \"application\" for WSGI to work\nfrom app import app as application  # noqa\n```\n\n4. Add the required environment variables to your app (replace `your_os_api_key` with your OS API key!)\n\n```console\ncd ~/usemap-rest\necho \"os_api_key=your_os_api_key\" \u003e\u003e .env\n```\n\nMore information is available in the 'Using a code sharing site like GitHub or BitBucket' section at [How to get your code in and out of PythonAnywhere](https://help.pythonanywhere.com/pages/UploadingAndDownloadingFiles/).\n\n### Production deploy to AWS\n\nThis solution is set up to use [Zappa](https://github.com/zappa/Zappa) to automate deployment to AWS. Zappa maintains:\n\n- The API deployed as an [AWS Lambda](https://aws.amazon.com/lambda/) function\n- An [AWS API Gateway](https://aws.amazon.com/api-gateway/) to trigger the Lamda function and provide URL security\n\nOn commit to the main branch (e.g. from a Pull Request), the Zappa CLI will run an update to make updates to the production deployment. This is configured with a GitHub action.\n\n## Authors\n\nSee the list of\n[contributors](https://github.com/geovation/usemap-rest/contributors)\nwho participated in this project.\n\n## License\n\nThis project is licensed under the [MIT](LICENSE)\nLicense - see the [LICENSE](LICENSE) file for\ndetails\n\n## Acknowledgments\n\n- [Developing RESTful APIs with Python and Flask](https://auth0.com/blog/developing-restful-apis-with-python-and-flask/)\n- [How to get your code in and out of PythonAnywhere](https://help.pythonanywhere.com/pages/UploadingAndDownloadingFiles/)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgeovation%2Fusemap-rest","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgeovation%2Fusemap-rest","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgeovation%2Fusemap-rest/lists"}